OpenAI Python SDK：3 万 Star 的官方 API 客户端，Python 调用 OpenAI 的标准选择

OpenAI 官方维护的 Python SDK，GitHub 上已经积累了 30,862 个 Star。对于用 Python 调用 OpenAI API 的开发者来说，这个库属于绕不开的基础设施。所有请求参数和响应字段都有类型定义，IDE 能自动补全，同步和异步两种客户端接口一致。

它解决了什么问题

OpenAI 的 REST API 接口有几十个，参数类型复杂，响应结构嵌套深。直接手写 HTTP 请求要处理认证、重试、超时、流式响应、错误分类，工作量不小。这个 SDK 把这些都封装好了，导入 OpenAI 类，设置 API Key，剩下的就是调用方法。

核心能力一览

同步和异步客户端。 同步用 OpenAI，异步用 AsyncOpenAI。异步底层基于 httpx，也支持切换成 aiohttp 以获得更高的并发性能。

流式响应。 支持 SSE，传 stream=True 就能逐条接收模型输出，同步和异步接口一样。

Realtime API。 通过 WebSocket 连接实现低延迟多模态对话，支持文本和音频输入输出。SDK 内部用 websockets 库管理连接，开发者不需要自己处理协议细节。

类型系统。 请求参数用 TypedDict，响应是 Pydantic 模型。响应对象可直接 .to_json() 序列化或 .to_dict() 转字典。VS Code 里开启 python.analysis.typeCheckingMode 即可获得字段级类型检查。

自动分页。 列表接口返回分页结果，SDK 提供自动翻页迭代器，直接用 for 循环遍历。需要精细控制时也可以用 .has_next_page() 和 .get_next_page() 逐页获取。

错误处理和重试。 所有错误继承 openai.APIError，按状态码分子类：BadRequestError、AuthenticationError、RateLimitError、InternalServerError 等。默认开启 2 次自动重试，覆盖连接错误、408、409、429 和 5xx，重试采用指数退避。超时默认 10 分钟，可全局或按请求配置。

Webhook 验证。 提供 client.webhooks.unwrap() 一步完成签名验证和负载解析，也提供 verify_signature() 让开发者单独验证后自行解析。

工作负载身份认证。 针对 Kubernetes、Azure、GCP 等云环境，支持通过短生命周期令牌进行身份认证，替代长期 API Key。

文件上传。 支持传 bytes、PathLike 对象或 (filename, contents, media type) 元组，异步客户端自动异步读取。

跨平台支持

除了标准 OpenAI API，SDK 内置了 Azure OpenAI 和 Amazon Bedrock 的支持。用 AzureOpenAI 类替换 OpenAI 就能接入 Azure 部署，BedrockOpenAI 类封装了 AWS bearer 认证和 Bedrock 端点，用法和标准客户端一致。

安装和版本

Python 3.9 以上，pip install openai 一行。版本策略遵循 SemVer，团队声明重视向后兼容。自定义 HTTP 行为方面，SDK 允许直接覆盖 httpx 客户端配置，代理、自定义传输层都支持。

适合谁用

如果你用 Python 接入 OpenAI API，这个 SDK 是官方推荐的路径。类型补全、自动重试、流式响应、分页迭代这些基础能力没必要自己实现，直接用官方维护的版本更省心。项目部署在 Azure 或 Bedrock 上的话，跨平台支持也能省掉不少适配工作。

。项目部署在 Azure 或 Bedrock 上的话，跨平台支持也能省掉不少适配工作。