OpenAI Python SDK 完整参考

基于 openai v2.36.0 官方源码 & README · 部署于 api-ref.karenepitaya.xyz/openai/

1. 安装 Installation

pip install openai

客户端初始化

from openai import OpenAI

# 默认从环境变量 OPENAI_API_KEY 读取
client = OpenAI()

# 显式传入
client = OpenAI(api_key="sk-...")

# 自定义 base_url（代理、兼容接口）
client = OpenAI(base_url="https://your-proxy.example.com/v1")

2. 快速开始 · Responses API 主推

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    instructions="You are a helpful assistant.",
    input="Explain quantum computing in one sentence.",
)

print(response.output_text)

核心参数

3. Chat Completions API 稳定接口

response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[
        {"role": "developer", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
    temperature=0.7,
    max_completion_tokens=500,
    top_p=1,
)

print(response.choices[0].message.content)

常用参数

Response 结构

response.id                          # "chatcmpl-xxx"
response.model                       # 实际使用的模型快照
response.choices[0].message.content  # 回复正文
response.choices[0].message.role     # "assistant"
response.choices[0].finish_reason    # "stop" | "length" | "content_filter"
response.usage.prompt_tokens         # 输入 token 数
response.usage.completion_tokens     # 输出 token 数
response.usage.total_tokens          # 总 token 数

4. 模型列表 Models

以下模型全部来自官方 SDK v2.36+ 源码。标注 Chat 表示可用于 Chat Completions API；标注 仅Resp 表示仅可用于 Responses API / AllModels，不支持 Chat Completions。

GPT-5.4 系列（最新旗舰）

GPT-5.3 / 5.2 / 5.1 系列

GPT-5 / GPT-4.1 系列

推理模型 o-series

经典模型（仍可用）

扩展模型（仅 Responses API / AllModels）

音频模型

图像模型

Embeddings 模型

5. 消息格式 & Vision

Chat Completions 消息角色

# developer 角色（推荐用作 system prompt，优先级高于 system）
{"role": "developer", "content": "You are a helpful assistant."}

# system 角色（仍可用）
{"role": "system", "content": "You are helpful."}

# user 角色
{"role": "user", "content": "Hello!"}

# assistant 角色
{"role": "assistant", "content": "Hi! How can I help?"}

Responses API 输入格式

# 简单文本（自动转为 list）
client.responses.create(model="gpt-5.4", input="Hello!")

# 结构化输入
client.responses.create(model="gpt-5.4", input=[
    {"role": "user", "content": "Hello!"}
])

Vision · 图片输入（Responses API）

response = client.responses.create(
    model="gpt-5.4",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What's in this image?"},
                {
                    "type": "input_image",
                    "image_url": "https://example.com/photo.jpg",
                },
            ],
        }
    ],
)

print(response.output_text)

Chat Completions 中的 Vision（旧格式）

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "图中有什么？"},
            {"type": "image_url", "image_url": {"url": "https://example.com/img.jpg"}},
        ],
    }],
)

6. Streaming 流式响应

Responses API 流式

stream = client.responses.create(
    model="gpt-5.4",
    input="Tell me a story.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

Chat Completions 流式

stream = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print(f"\n--- Tokens: {chunk.usage.total_tokens} ---")

7. Function Calling / Tools

Responses API（推荐）

response = client.responses.create(
    model="gpt-5.4",
    input="What's the weather in Beijing?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"},
            },
            "required": ["city"],
        },
    }],
)

Chat Completions API

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather by city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"],
            "additionalProperties": False,
        },
    },
}]

response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "Beijing weather?"}],
    tools=tools,
    tool_choice="auto",
)

tool_calls = response.choices[0].message.tool_calls

8. Structured Outputs

Responses API · JSON Schema

response = client.responses.create(
    model="gpt-5.4",
    input="List 3 famous physicists with their birth years.",
    text={
        "format": {
            "type": "json_schema",
            "name": "physicists",
            "schema": {
                "type": "object",
                "properties": {
                    "physicists": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "birth_year": {"type": "integer"},
                            },
                            "required": ["name", "birth_year"],
                        },
                    }
                },
                "required": ["physicists"],
            },
        }
    },
)

print(response.output_text)  # valid JSON matching schema

Chat Completions · JSON Schema

response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "List 3 planets with their moons count."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "planets",
            "schema": {
                "type": "object",
                "properties": {
                    "planets": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "moons": {"type": "integer"},
                            },
                            "required": ["name", "moons"],
                            "additionalProperties": False,
                        },
                    }
                },
                "required": ["planets"],
                "additionalProperties": False,
            },
            "strict": True,
        },
    },
)

import json
data = json.loads(response.choices[0].message.content)

9. 音频 Audio · TTS + STT

TTS · 文本转语音

# 生成语音
response = client.audio.speech.create(
    model="gpt-4o-mini-tts",
    voice="alloy",
    input="Hello world",
)

# 保存到文件
response.stream_to_file("output.mp3")

# 或写入 BytesIO
response.write_to_file("output.mp3")

STT · 语音转文本（Transcription）

# 音频转录
audio = open("audio.mp3", "rb")
transcript = client.audio.transcriptions.create(
    model="gpt-4o-mini-transcribe",
    file=audio,
    language="zh",
)

print(transcript.text)

音频翻译（Translation）

audio = open("audio.mp3", "rb")
translation = client.audio.translations.create(
    model="whisper-1",
    file=audio,
)

print(translation.text)  # translated to English

10. 图像 Images

图像生成

response = client.images.generate(
    model="gpt-image-2",
    prompt="A cat sitting in moonlight, digital art style",
    size="1024x1024",
    quality="standard",
    n=1,
)

image_url = response.data[0].url
print(image_url)

# 或获取 base64
# b64_json = response.data[0].b64_json

图像编辑

response = client.images.edit(
    model="dall-e-2",
    image=open("original.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="Add a rainbow in the sky",
    size="1024x1024",
)

图像变体

response = client.images.create_variation(
    model="dall-e-2",
    image=open("original.png", "rb"),
    n=3,
)

11. Embeddings

# 基础用法
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Hello world",
    encoding_format="float",
)

vector = response.data[0].embedding  # list[float]
print(len(vector))                    # 1536

# 批量输入
response = client.embeddings.create(
    model="text-embedding-3-large",
    input=["Hello world", "Goodbye world"],
    dimensions=1024,  # 可选降维，减少存储
)

for item in response.data:
    print(len(item.embedding))  # 1024

12. 错误处理 Error Handling

from openai import (
    APIError,
    APIConnectionError,
    APITimeoutError,
    RateLimitError,
    AuthenticationError,
    PermissionDeniedError,
    NotFoundError,
    BadRequestError,
    UnprocessableEntityError,
    InternalServerError,
    APIStatusError,
)

import time

try:
    response = client.chat.completions.create(
        model="gpt-5.2",
        messages=[{"role": "user", "content": "Hello"}],
    )
except AuthenticationError:
    print("❌ API Key 无效 (401)")
except PermissionDeniedError:
    print("❌ 权限不足 (403)")
except NotFoundError:
    print("❌ 资源不存在 (404)")
except RateLimitError:
    print("⏳ 速率限制，等待后重试 (429)")
    time.sleep(5)
except BadRequestError as e:
    print(f"❌ 请求参数错误 (400): {e}")
except UnprocessableEntityError as e:
    print(f"❌ 验证错误 (422): {e}")
except InternalServerError:
    print("❌ 服务器内部错误 (500+)")
except APIConnectionError:
    print("❌ 网络连接失败")
except APITimeoutError:
    print("❌ 请求超时")
except APIStatusError as e:
    print(f"❌ HTTP 状态错误: {e.status_code}")
except APIError as e:
    print(f"❌ API 错误: {e}")

13. 配置 Configuration

超时控制

# 默认超时: 10 分钟 (600 秒)
client = OpenAI()

# 全局超时
client = OpenAI(timeout=30.0)  # 30 秒

# 单次请求超时
response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "Hello"}],
    timeout=15.0,  # 仅此请求 15 秒
)

自动重试

# 自定义重试
client = OpenAI(max_retries=5)   # 最多重试 5 次
client = OpenAI(max_retries=0)   # 禁用自动重试

代理 Proxy

# 通过 httpx 代理
import httpx

client = OpenAI(
    http_client=httpx.Client(proxy="http://user:pass@proxy.example.com:8080"),
)

自定义 base_url

# 自建代理 / 兼容接口
client = OpenAI(base_url="https://your-proxy.example.com/v1")

# 常用例子：通过 One API / FastGPT 等网关访问
client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.openai-forward.com/v1",
)

其他配置选项

client = OpenAI(
    api_key="sk-...",              # API 密钥
    organization="org-...",        # 组织 ID
    base_url="https://...",        # 自定义端点
    timeout=60.0,                  # 请求超时（秒）
    max_retries=2,                 # 最大重试次数
    default_headers={"X-My-Header": "value"},
    default_query={"api-version": "2024-02-01"},
)

14. 异步 Async

import asyncio
from openai import AsyncOpenAI

async def main():
    client = AsyncOpenAI()

    # 异步调用
    response = await client.responses.create(
        model="gpt-5.4",
        input="Hello!",
    )
    print(response.output_text)

    # 异步流式
    stream = await client.responses.create(
        model="gpt-5.4",
        input="Tell me a joke.",
        stream=True,
    )
    async for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="")

    # 并发处理多个请求
    tasks = [
        client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": f"Topic {i}"}],
        )
        for i in range(5)
    ]
    results = await asyncio.gather(*tasks)
    for r in results:
        print(r.choices[0].message.content)

asyncio.run(main())

15. Azure OpenAI

from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="https://your-resource.openai.azure.com/",
    api_key="your-azure-api-key",
    api_version="2024-10-01-preview",
)

response = client.chat.completions.create(
    model="gpt-4o",  # 部署名称
    messages=[{"role": "user", "content": "Hello"}],
)

print(response.choices[0].message.content)

Azure 异步

from openai import AsyncAzureOpenAI

client = AsyncAzureOpenAI(
    azure_endpoint="https://your-resource.openai.azure.com/",
    api_key="your-azure-api-key",
    api_version="2024-10-01-preview",
)

response = await client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

16. Realtime API

from openai import OpenAI

client = OpenAI()

# WebSocket 连接
async with client.realtime.connect(model="gpt-realtime") as conn:
    # 发送音频/文本
    await conn.send({
        "type": "conversation.item.create",
        "item": {
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "Hello!"}],
        },
    })

    # 触发响应
    await conn.send({"type": "response.create"})

    # 接收事件
    async for event in conn:
        print(event.type, event)

17. Vector Stores · 文件搜索

from openai import OpenAI

client = OpenAI()

# 创建 Vector Store
vector_store = client.vector_stores.create(
    name="my_knowledge_base",
)

# 上传文件
file = client.files.create(
    file=open("document.pdf", "rb"),
    purpose="assistants",
)

# 将文件添加到 Vector Store
client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file.id,
)

# 搜索
results = client.vector_stores.search(
    vector_store_id=vector_store.id,
    query="What is the main topic?",
    max_num_results=5,
)

for result in results.data:
    print(result.content[0].text)

结合 Responses API 使用 File Search

response = client.responses.create(
    model="gpt-5.4",
    input="What documents mention the project timeline?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "max_num_results": 5,
    }],
)

print(response.output_text)

18. Assistants API

from openai import OpenAI

client = OpenAI()

# 创建 Assistant
assistant = client.beta.assistants.create(
    name="Math Tutor",
    instructions="You are a personal math tutor. Explain step by step.",
    model="gpt-5.2",
    tools=[{"type": "code_interpreter"}],
)

# 创建 Thread（对话线程）
thread = client.beta.threads.create()

# 添加用户消息
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Solve 3x + 5 = 20",
)

# 运行 Assistant
run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id,
)

# 轮询等待结果
import time
while run.status in ("queued", "in_progress"):
    time.sleep(1)
    run = client.beta.threads.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id,
    )

# 获取回复
messages = client.beta.threads.messages.list(thread_id=thread.id)
for msg in messages.data:
    if msg.role == "assistant":
        print(msg.content[0].text.value)

Batch 批处理

from openai import OpenAI

client = OpenAI()

# 创建批处理作业
batch = client.batches.create(
    input_file_id="file-xxx",
    endpoint="/v1/chat/completions",
    completion_window="24h",
)

# 查询状态
batch = client.batches.retrieve(batch.id)
print(batch.status)  # validating | in_progress | finalizing | completed | failed

Files API

# 上传文件
file = client.files.create(
    file=open("data.jsonl", "rb"),
    purpose="batch",
)

# 列出文件
for f in client.files.list():
    print(f.id, f.filename)

# 获取文件内容
content = client.files.content(file.id)
print(content.text)

Models API

# 列出所有可用模型
models = client.models.list()
for model in models:
    print(model.id)

# 获取特定模型信息
model = client.models.retrieve("gpt-5.4")
print(model.id, model.created)

Moderations

response = client.moderations.create(
    model="text-moderation-latest",
    input="Some text to check",
)
print(response.results[0].flagged)  # bool

Uploads API

upload = client.uploads.create(
    filename="large_file.jsonl",
    purpose="batch",
    bytes=file_size,
)
# 分块上传
client.uploads.upload_part(
    upload_id=upload.id,
    data=chunk_data,
)
client.uploads.complete(upload_id=upload.id)

Fine-tuning

# 创建微调作业
job = client.fine_tuning.jobs.create(
    training_file="file-xxx",
    model="gpt-4o-mini",
)

# 列出微调作业
for job in client.fine_tuning.jobs.list():
    print(job.id, job.status)

# 获取特定作业事件
events = client.fine_tuning.jobs.list_events(fine_tuning_job_id=job.id)
for event in events:
    print(event.message)

Webhooks

# Webhooks 用于接收异步事件回调
# 详见 SDK 文档: client.webhooks.*

API 资源总览

OpenAI Python SDK 完整参考 · v2.36.0 · api-ref.karenepitaya.xyz