OpenAI Python API 库

OpenAI Python 库为所有 Python 3.9+ 应用程序提供了便捷的 OpenAI REST API 访问方式。该库包含所有请求参数和响应字段的类型定义，并提供基于 httpx 的同步和异步客户端。

它由我们的 OpenAPI 规范 使用 Stainless 生成。

文档

REST API 文档可在 platform.openai.com 上找到。本库的完整 API 可在 api.md 中查阅。

安装

# 从 PyPI 安装
pip install openai

使用

本库的完整 API 可在 api.md 中查阅。

与 OpenAI 模型交互的主要 API 是 Responses API。您可以通过以下代码从模型生成文本：

import os
from openai import OpenAI

client = OpenAI(
    # 这是默认值，可以省略
    api_key=os.environ.get("OPENAI_API_KEY"),
)

response = client.responses.create(
    model="gpt-5.2",
    instructions="你是一位说话像海盗的编程助手。",
    input="如何检查一个 Python 对象是否是某个类的实例？"
)

print(response.output_text)

之前的标准（无限期支持）文本生成方法是 Chat Completions API。您可以使用该 API 通过以下代码从模型生成文本：

from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5.2",
    messages=[
        {"role": "developer", "content": "像海盗一样说话。"},
        {
            "role": "user",
            "content": "如何检查一个 Python 对象是否是某个类的实例？"
        },
    ],
)

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

虽然您可以直接传递 api_key 关键字参数，但我们建议使用 python-dotenv 将 OPENAI_API_KEY="My API Key" 添加到您的 .env 文件中，以避免将 API 密钥存储在版本控制系统中。在此处获取 API 密钥。

视觉功能

使用图片 URL：

prompt = "这张图片里有什么？"
img_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/d5/2023_06_08_Raccoon1.jpg/1599px-2023_06_08_Raccoon1.jpg"

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": prompt},
                {"type": "input_image", "image_url": f"{img_url}"},
            ],
        }
    ],
)

使用 Base64 编码的图片字符串：

import base64
from openai import OpenAI

client = OpenAI()

prompt = "这张图片里有什么？"
with open("path/to/image.png", "rb") as image_file:
    b64_image = base64.b64encode(image_file.read()).decode("utf-8")

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": prompt},
                {"type": "input_image", "image_url": f"data:image/png;base64,{b64_image}"},
            ],
        }
    ],
)

异步使用

只需导入 AsyncOpenAI 而不是 OpenAI，并在每次 API 调用前加上 await 即可：

import os
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    # 这是默认值，可以省略
    api_key=os.environ.get("OPENAI_API_KEY"),
)


async def main() -> None:
    response = await client.responses.create(
        model="gpt-5.2", input="给一个聪明的五岁孩子解释一下‘disestablishmentarianism’是什么意思。"
    )
    print(response.output_text)


asyncio.run(main())

同步和异步客户端的功能完全相同。

使用 aiohttp

默认情况下，异步客户端使用 httpx 处理 HTTP 请求。然而，为了提升并发性能，您也可以选择使用 aiohttp 作为 HTTP 后端。

您可以通过安装 aiohttp 来启用此功能：

# 从 PyPI 安装
pip install openai[aiohttp]

然后，在实例化客户端时指定 http_client=DefaultAioHttpClient() 即可启用：

import os
import asyncio
from openai import DefaultAioHttpClient
from openai import AsyncOpenAI


async def main() -> None:
    async with AsyncOpenAI(
        api_key=os.environ.get("OPENAI_API_KEY"),  # 这是默认值，可以省略
        http_client=DefaultAioHttpClient(),
    ) as client:
        chat_completion = await client.chat.completions.create(
            messages=[
                {
                    "role": "user",
                    "content": "说这是个测试",
                }
            ],
            model="gpt-5.2",
        )


asyncio.run(main())

流式响应

我们支持使用服务器发送事件 (SSE) 实现流式响应。

from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="gpt-5.2",
    input="写一个关于独角兽的一句话睡前故事。",
    stream=True,
)

for event in stream:
    print(event)

异步客户端使用完全相同的接口：

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()


async def main():
    stream = await client.responses.create(
        model="gpt-5.2",
        input="写一个关于独角兽的一句话睡前故事。",
        stream=True,
    )

    async for event in stream:
        print(event)


asyncio.run(main())

实时 API

实时 API 使您能够构建低延迟、多模态的对话体验。目前，它支持文本和音频作为输入和输出，并通过 WebSocket 连接实现 函数调用。

在底层，SDK 使用 websockets 库来管理连接。

实时 API 通过客户端发送事件和服务器发送事件相结合的方式工作。客户端可以发送事件来更新会话配置或发送文本和音频输入。服务器事件则用于确认音频响应已完成，或已收到模型的文本响应。完整的事件参考可以在 这里 找到，相关指南则可在 这里 查阅。

基于文本的基本示例：

import asyncio
from openai import AsyncOpenAI

async def main():
    client = AsyncOpenAI()

    async with client.realtime.connect(model="gpt-realtime") as connection:
        await connection.session.update(
            session={"type": "realtime", "output_modalities": ["text"]}
        )

        await connection.conversation.item.create(
            item={
                "type": "message",
                "role": "user",
                "content": [{"type": "input_text", "text": "Say hello!"}],
            }
        )
        await connection.response.create()

        async for event in connection:
            if event.type == "response.output_text.delta":
                print(event.delta, flush=True, end="")

            elif event.type == "response.output_text.done":
                print()

            elif event.type == "response.done":
                break

asyncio.run(main())

然而，实时 API 的真正魔力在于处理音频输入/输出。请参阅此示例 TUI 脚本，以获取一个完整的示例。

实时错误处理

每当发生错误时，实时 API 都会发送一个 error 事件，并且连接将保持打开状态，仍可继续使用。这意味着您需要自行处理这些错误，因为当 error 事件到来时，SDK 并不会直接抛出任何异常。

client = AsyncOpenAI()

async with client.realtime.connect(model="gpt-realtime") as connection:
    ...
    async for event in connection:
        if event.type == 'error':
            print(event.error.type)
            print(event.error.code)
            print(event.error.event_id)
            print(event.error.message)

使用类型

嵌套请求参数是 TypedDicts。响应则是 Pydantic 模型，它们还提供了诸如以下功能的辅助方法：

• 将模型序列化回 JSON：model.to_json()
• 转换为字典：model.to_dict()

使用类型化的请求和响应可以在编辑器中获得自动补全和文档提示。如果您希望在 VS Code 中看到类型错误以帮助更早地捕获 bug，请将 python.analysis.typeCheckingMode 设置为 basic。

分页

OpenAI API 中的列表方法都进行了分页处理。

该库为每个列表响应提供了自动分页迭代器，因此您无需手动请求后续页面：

from openai import OpenAI

client = OpenAI()

all_jobs = []
# 根据需要自动获取更多页面。
for job in client.fine_tuning.jobs.list(
    limit=20,
):
    # 在此处对 job 做些处理
    all_jobs.append(job)
print(all_jobs)

或者，以异步方式：

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()


async def main() -> None:
    all_jobs = []
    # 遍历所有页面中的项目，按需发出请求。
    async for job in client.fine_tuning.jobs.list(
        limit=20,
    ):
        all_jobs.append(job)
    print(all_jobs)


asyncio.run(main())

此外，您还可以使用 .has_next_page()、.next_page_info() 或 .get_next_page() 方法来更精细地控制分页操作：

first_page = await client.fine_tuning.jobs.list(
    limit=20,
)
if first_page.has_next_page():
    print(f"将使用以下信息获取下一页: {first_page.next_page_info()}")
    next_page = await first_page.get_next_page()
    print(f"我们刚刚获取的项目数量: {len(next_page.data)}")

# 如果是非异步使用，则移除 `await`。

或者直接操作返回的数据：

first_page = await client.fine_tuning.jobs.list(
    limit=20,
)

print(f"下一页游标: {first_page.after}")  # => "下一页游标: ..."
for job in first_page.data:
    print(job.id)

# 如果是非异步使用，则移除 `await`。

嵌套参数

嵌套参数是使用 TypedDict 类型化的字典，例如：

from openai import OpenAI

client = OpenAI()

response = client.chat.responses.create(
    input=[
        {
            "role": "user",
            "content": "How much ?",
        }
    ],
    model="gpt-5.2",
    response_format={"type": "json_object"},
)

文件上传

与文件上传相对应的请求参数可以以 bytes 形式传递，也可以传递一个 PathLike 实例，或一个包含 (文件名, 内容, 媒体类型) 的元组。

from pathlib import Path
from openai import OpenAI

client = OpenAI()

client.files.create(
    file=Path("input.jsonl"),
    purpose="fine-tune",
)

异步客户端使用完全相同的接口。如果您传递一个 PathLike 实例，文件内容将被自动异步读取。

Webhook 验证

验证 webhook 签名是 可选但推荐的做法。

有关 Webhook 的更多信息，请参阅 API 文档。

解析 Webhook 负载

对于大多数用例，您可能希望同时验证 Webhook 并解析负载。为此，我们提供了 client.webhooks.unwrap() 方法，该方法会解析 Webhook 请求并验证其是否由 OpenAI 发送。如果签名无效，此方法将引发错误。

请注意，body 参数必须是服务器发送的原始 JSON 字符串（不要先对其进行解析）。.unwrap() 方法会在验证 Webhook 确实来自 OpenAI 后，为您将此 JSON 解析为事件对象。

from openai import OpenAI
from flask import Flask, request

app = Flask(__name__)
client = OpenAI()  # 默认使用 OPENAI_WEBHOOK_SECRET 环境变量


@app.route("/webhook", methods=["POST"])
def webhook():
    request_body = request.get_data(as_text=True)

    try:
        event = client.webhooks.unwrap(request_body, request.headers)

        if event.type == "response.completed":
            print("响应已完成:", event.data)
        elif event.type == "response.failed":
            print("响应失败:", event.data)
        else:
            print("未处理的事件类型:", event.type)

        return "ok"
    except Exception as e:
        print("无效签名:", e)
        return "无效签名", 400


if __name__ == "__main__":
    app.run(port=8000)

直接验证 Webhook 负载

在某些情况下，您可能希望将 Webhook 的验证与负载解析分开进行。如果您更倾向于分别处理这些步骤，我们提供了 client.webhooks.verify_signature() 方法，用于仅验证 Webhook 请求的签名。与 .unwrap() 方法类似，如果签名无效，此方法也会引发错误。

请注意，body 参数必须是服务器发送的原始 JSON 字符串（不要先对其进行解析）。验证签名后，您需要自行解析请求体。

import json
from openai import OpenAI
from flask import Flask, request

app = Flask(__name__)
client = OpenAI()  # 默认使用 OPENAI_WEBHOOK_SECRET 环境变量


@app.route("/webhook", methods=["POST"])
def webhook():
    request_body = request.get_data(as_text=True)

    try:
        client.webhooks.verify_signature(request_body, request.headers)

        # 验证后解析请求体
        event = json.loads(request_body)
        print("已验证的事件:", event)

        return "ok"
    except Exception as e:
        print("无效签名:", e)
        return "无效签名", 400


if __name__ == "__main__":
    app.run(port=8000)

错误处理

当库无法连接到 API 时（例如，由于网络连接问题或超时），会引发 openai.APIConnectionError 的子类异常。

当 API 返回非成功状态码（即 4xx 或 5xx 响应）时，会引发 openai.APIStatusError 的子类异常，其中包含 status_code 和 response 属性。

所有错误都继承自 openai.APIError。

import openai
from openai import OpenAI

client = OpenAI()

try:
    client.fine_tuning.jobs.create(
        model="gpt-4o",
        training_file="file-abc123",
    )
except openai.APIConnectionError as e:
    print("无法连接到服务器")
    print(e.__cause__)  # 底层异常，很可能是在 httpx 内部引发的。
except openai.RateLimitError as e:
    print("收到 429 状态码；我们应该稍作退避。")
except openai.APIStatusError as e:
    print("收到了另一个非 200 范围的状态码")
    print(e.status_code)
    print(e.response)

错误代码如下：

状态码	错误类型
400	BadRequestError
401	AuthenticationError
403	PermissionDeniedError
404	NotFoundError
422	UnprocessableEntityError
429	RateLimitError
>=500	InternalServerError
N/A	APIConnectionError

请求 ID

更多关于调试请求的信息，请参阅 这些文档

SDK 中的所有对象响应都提供 _request_id 属性，该属性来自 x-request-id 响应头，以便您可以快速记录失败的请求并将其报告给 OpenAI。

response = await client.responses.create(
    model="gpt-5.2",
    input="说‘这是一个测试’。",
)
print(response._request_id)  # req_123

请注意，与其他以 _ 为前缀的属性不同，_request_id 属性是公开的。除非另有说明，否则所有其他以 _ 为前缀的属性、方法和模块都是私有的。

[!IMPORTANT]
如果您需要访问失败请求的请求 ID，必须捕获 APIStatusError 异常。

import openai

try:
    completion = await client.chat.completions.create(
        messages=[{"role": "用户", "内容": "说‘这是一个测试’"}], 模型为“gpt-5.2”
    )
except openai.APIStatusError as exc:
    print(exc.request_id)  # req_123
    raise exc

重试

默认情况下，某些错误会自动重试 2 次，并采用短时间的指数退避策略。连接错误（例如，由于网络连接问题）、408 请求超时、409 冲突、429 速率限制以及 >=500 内部错误都会默认重试。

您可以使用 max_retries 选项来配置或禁用重试设置：

from openai import OpenAI

# 配置所有请求的默认值：
client = OpenAI(
    # 默认值为 2
    max_retries=0,
)

# 或者按请求配置：
client.with_options(max_retries=5).chat.completions.create(
    messages=[
        {
            "role": "用户",
            "内容": "如何用 JavaScript 获取当前日期的名称？",
        }
    ],
    模型为“gpt-5.2”
)

超时

默认情况下，请求会在 10 分钟后超时。您可以使用 timeout 选项进行配置，该选项接受浮点数或 httpx.Timeout 对象：

from openai import OpenAI

# 配置所有请求的默认值：
client = OpenAI(
    # 20 秒（默认为 10 分钟）
    timeout=20.0,
)

# 更精细的控制：
client = OpenAI(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# 按请求覆盖：
client.with_options(timeout=5.0).chat.completions.create(
    messages=[
        {
            "role": "用户",
            "内容": "如何用 Python 列出目录中的所有文件？",
        }
    ],
    模型为“gpt-5.2”
)

超时时，会抛出 APITimeoutError。

请注意，超时的请求会默认重试两次（见“重试”部分）。

高级

日志记录

我们使用标准库中的 logging 模块。

您可以通过将环境变量 OPENAI_LOG 设置为 info 来启用日志记录。

$ export OPENAI_LOG=info

或者将其设置为 debug 以获得更详细的日志输出。

如何判断 None 是表示 null 还是缺失

在 API 响应中，某个字段可能显式地为 null，也可能完全不存在；无论哪种情况，在本库中其值都为 None。您可以通过 .model_fields_set 来区分这两种情况：

if response.my_field is None:
  if 'my_field' not in response.model_fields_set:
    print('收到的 JSON 类似于 {}, 根本没有 "my_field" 键。')
  else:
    print('收到的 JSON 类似于 {"my_field": null}。')

访问原始响应数据（例如头部信息）

可以通过在任何 HTTP 方法调用前加上 .with_raw_response. 来访问“原始”响应对象，例如：

from openai import OpenAI

client = OpenAI()
response = client.chat.completions.with_raw_response.create(
    messages=[{
        "role": "user",
        "content": "说这是个测试",
    }],
    model="gpt-5.2",
)
print(response.headers.get('X-My-Header'))

completion = response.parse()  # 获取 `chat.completions.create()` 本来会返回的对象
print(completion)

这些方法会返回一个 LegacyAPIResponse 对象。这是一个遗留类，因为我们在下一个主要版本中会对其进行小幅改动。

对于同步客户端，这基本上与之前相同，唯一的区别是 content 和 text 将变为方法而不是属性。而在异步客户端中，所有方法都是异步的。

我们将提供迁移脚本，并且整体迁移过程应该会比较顺利。

.with_streaming_response

上述接口会在发出请求时立即读取完整的响应体，但这并不总是您所需要的。

如果需要流式传输响应体，请改用 .with_streaming_response，它需要使用上下文管理器，并且只有在您调用 .read()、.text()、.json()、.iter_bytes()、.iter_text()、.iter_lines() 或 .parse() 时才会读取响应体。在异步客户端中，这些方法都是异步的。

因此，.with_streaming_response 方法会返回不同的 APIResponse 对象，而异步客户端则返回 AsyncAPIResponse 对象。

with client.chat.completions.with_streaming_response.create(
    messages=[
        {
            "role": "user",
            "content": "说这是个测试",
        }
    ],
    model="gpt-5.2",
) as response:
    print(response.headers.get("X-My-Header"))

    for line in response.iter_lines():
        print(line)

必须使用上下文管理器，以确保响应能够可靠地关闭。

发起自定义或未文档化的请求

本库经过类型标注，方便用户访问已文档化的 API。

如果您需要访问未文档化的端点、参数或响应属性，仍然可以使用本库。

未文档化的端点

要向未文档化的端点发起请求，您可以使用 client.get、client.post 等 HTTP 方法。在发起此类请求时，客户端上的选项（如重试次数）仍会被尊重。

import httpx

response = client.post(
    "/foo",
    cast_to=httpx.Response,
    body={"my_param": True},
)

print(response.headers.get("x-foo"))

未文档化的请求参数

如果您想明确发送额外的参数，可以使用 extra_query、extra_body 和 extra_headers 请求选项来实现。

未文档化的响应属性

要访问未文档化的响应属性，您可以直接访问诸如 response.unknown_prop 之类的额外字段。此外，您还可以通过 response.model_extra 将 Pydantic 模型上的所有额外字段作为字典获取。

配置 HTTP 客户端

您可以直接覆盖 httpx 客户端，以根据您的使用场景进行自定义，包括：

• 支持 代理
• 自定义 传输层
• 其他 高级功能

import httpx
from openai import OpenAI, DefaultHttpxClient

client = OpenAI(
    # 或者使用 `OPENAI_BASE_URL` 环境变量
    base_url="http://my.test.server.example.com:8083/v1",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

您也可以通过使用 with_options() 在每次请求时自定义客户端：

client.with_options(http_client=DefaultHttpxClient(...))

管理 HTTP 资源

默认情况下，当客户端被 垃圾回收 时，库会自动关闭底层的 HTTP 连接。如果您希望手动关闭客户端，可以使用 .close() 方法，或者使用上下文管理器在退出时自动关闭。

from openai import OpenAI

with OpenAI() as client:
  # 在这里发起请求
  ...

# 此时 HTTP 客户端已被关闭

Microsoft Azure OpenAI

要将本库与 Azure OpenAI 一起使用，应使用 AzureOpenAI 类，而不是 OpenAI 类。

[!重要] Azure API 的结构与核心 API 不同，这意味着响应和参数的静态类型并不总是正确的。

from openai import AzureOpenAI

# 从环境变量 AZURE_OPENAI_API_KEY 中获取 API 密钥
client = AzureOpenAI(
    # https://learn.microsoft.com/azure/ai-services/openai/reference#rest-api-versioning
    api_version="2023-07-01-preview",
    # https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource?pivots=web-portal#create-a-resource
    azure_endpoint="https://example-endpoint.openai.azure.com",
)

completion = client.chat.completions.create(
    model="deployment-name",  # 例如 gpt-35-instant
    messages=[
        {
            "role": "user",
            "content": "如何使用 Python 输出目录中的所有文件？",
        },
    ],
)
print(completion.to_json())

除了基础 OpenAI 客户端提供的选项之外，还提供了以下选项：

• azure_endpoint（或环境变量 AZURE_OPENAI_ENDPOINT）
• azure_deployment
• api_version（或环境变量 OPENAI_API_VERSION）
• azure_ad_token（或环境变量 AZURE_OPENAI_AD_TOKEN）
• azure_ad_token_provider

使用 Microsoft Entra ID（以前称为 Azure Active Directory）的客户端示例可以在此处找到：https://github.com/openai/openai-python/blob/main/examples/azure_ad.py。

版本控制

本包通常遵循 SemVer 规范，但某些不向后兼容的更改可能会以次要版本发布：

1. 仅影响静态类型而不破坏运行时行为的更改。
2. 对库内部实现的更改，这些实现虽然在技术上是公开的，但并非设计用于外部使用或未被文档化。 (如果您依赖于此类内部实现，请通过 GitHub 提交 issue 告知我们。)
3. 我们预计在实际应用中不会影响绝大多数用户的更改。

我们非常重视向后兼容性，并努力确保您能够获得顺畅的升级体验。

我们非常欢迎您的反馈，请在 issue 中提出问题、报告 bug 或给出建议。

确定已安装的版本

如果您已经升级到最新版本，但仍未看到预期的新功能，则很可能您的 Python 环境仍在使用旧版本。

您可以通过以下方式确定运行时正在使用的版本：

import openai
print(openai.__version__)

系统要求

Python 3.9 或更高版本。

贡献

请参阅 贡献文档。

OpenAI Python SDK 快速上手指南

环境准备

• Python 版本：需要 Python 3.9 或更高版本。
• API Key：请提前在 OpenAI 平台 获取 API Key。
• 环境变量（推荐）：建议安装 python-dotenv 并将 Key 存入 .env 文件，避免硬编码在代码中。

  pip install python-dotenv
  

  在项目根目录创建 .env 文件，内容如下：

  OPENAI_API_KEY="你的 API Key"
  

安装步骤

通过 PyPI 安装官方库：

pip install openai

提示：如果在国内网络环境下安装较慢，可使用国内镜像源加速：

pip install openai -i https://pypi.tuna.tsinghua.edu.cn/simple

若需使用异步高性能后端（可选），可安装 aiohttp 支持：

pip install openai[aiohttp]

基本使用

1. 初始化客户端

推荐使用环境变量自动加载 API Key：

import os
from openai import OpenAI

client = OpenAI(
    # 默认会自动读取 OPENAI_API_KEY 环境变量，也可手动传入
    api_key=os.environ.get("OPENAI_API_KEY"),
)

2. 调用对话接口 (Chat Completions)

这是最通用的文本生成方式：

completion = client.chat.completions.create(
    model="gpt-4o",  # 或 gpt-3.5-turbo 等可用模型
    messages=[
        {"role": "system", "content": "你是一个乐于助人的助手。"},
        {"role": "user", "content": "如何用 Python 检查对象是否为类的实例？"},
    ],
)

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

3. 调用最新 Responses 接口

OpenAI 推出的新一代交互接口，支持更灵活的指令控制：

response = client.responses.create(
    model="gpt-4o",
    instructions="你是一个像海盗一样说话的编程助手。",
    input="如何用 Python 检查对象是否为类的实例？",
)

print(response.output_text)

4. 异步使用 (Async)

如需在高并发场景下使用，可导入 AsyncOpenAI 并配合 async/await：

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()

async def main():
    response = await client.responses.create(
        model="gpt-4o",
        input="向一个聪明的五岁孩子解释去建制主义。",
    )
    print(response.output_text)

asyncio.run(main())