OpenAI API接口使用基础教程
Official Python 库 — OpenAI API
这是 OpenAI 官方为 Python（支持 Python 3.8 及以上）提供的 REST API 客户端，使用现代的 httpx 库实现同步与异步调用，并内置完整的类型定义 ([github.com][1])。
文档
- REST API 的官方文档请参考 platform.openai.com。
- 本库完整 API 说明可见
api.md文件 ([github.com][1])。
安装
pip install openai
️ 基本用法
核心实例：Responses API (用于 GPT-4o 等模型)
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
response = client.responses.create(
model="gpt-4o",
instructions="你是一个海盗风格的编程助手。",
input="如何判断一个 Python 对象是否是某个类的实例？",
)
print(response.output_text)
兼容聊天接口：Chat Completions
from openai import OpenAI
client = OpenAI()
completion = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "developer", "content": "说话像海盗。"},
{"role": "user", "content": "怎么检查一个 Python 对象是否是某个类的实例？"},
],
)
print(completion.choices[0].message.content)
建议使用 python-dotenv 保持 OPENAI_API_KEY 不写进代码 ([github.com][1])。
️ 图像理解支持（Vision）
示例如下：
-
使用图片 URL：
response = client.responses.create( model="gpt-4o-mini", input=[{ "role": "user", "content": [ {"type": "input_text", "text": "这张图片里有什么？"}, {"type": "input_image", "image_url": img_url}, ], }], ) -
使用 Base64 图像字符串：
b64 = base64.b64encode(open(...).read()).decode() client.responses.create( model="gpt-4o-mini", input=[{"role":"user","content":[{"type":"input_text","text":"图片内容？"},{"type":"input_image","image_url":f"data:image/png;base64,{b64}"}]}], )
⏩ 异步用法
使用 AsyncOpenAI 客户端并在协程中 await 调用：
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
async def main():
resp = await client.responses.create(model="gpt-4o", input="向五岁儿童解释‘反设教主义’")
print(resp.output_text)
asyncio.run(main())
功能与同步版基本一致 ([github.com][1])。
⚙️ 使用 aiohttp 作为后端
pip install openai[aiohttp]
然后：
from openai import AsyncOpenAI, DefaultAioHttpClient
async with AsyncOpenAI(http_client=DefaultAioHttpClient()) as client:
# ...
适合对并发性能有要求的场景 。
流式响应
开启 stream=True 可逐行读取模型生成的响应：
for event in client.responses.create(model="gpt-4o", input="写一句独角兽童话", stream=True):
print(event)
异步端同理 ([github.com][1])。
Realtime API（测试版）
支持通过 WebSocket 进行包含文本、音频输入输出和函数调用的低延迟对话。
示例略，但已在 README 中提供 ([github.com][1])。
类型与自动补全
- 请求参数使用
TypedDict； - 响应使用 Pydantic 模型；
- 支持
.to_json()/.to_dict()，并为 IDE 提供类型提示 ([github.com][1])。
分页处理
库提供自动分页迭代器，便于获取大型列表（如 fine-tuning 任务）：
for job in client.fine_tuning.jobs.list(limit=20):
print(job.id)
异步版本同理 ([github.com][1])。
文件上传
支持上传本地文件或 bytes、Pathlike：
client.files.create(file=Path("file.jsonl"), purpose="fine-tune")
异步客户端支持异步读取 ([github.com][1])。
异常与错误处理
- 网络连接错误会抛
APIConnectionError； - API 返回非 2xx 会抛对应错误（如
RateLimitError、APIStatusError等）； - 错误继承自
APIError； - 可使用
try…except捕获并获取.status_code或.request_id([github.com][1])。
支持自动重试（默认 2 次），可配置 max_retries 和 timeout([github.com][1])。
⚙️ 高级用法
- 日志：设置环境变量
OPENAI_LOG=info或debug； - 辨别 None 是缺失还是 explicit
null； - 访问原始 HTTP 响应
.with_raw_response; - 使用
.with_streaming_response获取流式原始响应； - 可发起未记录的自定义 request；
- 可配置自定义 HTTP 客户端（代理、传输层等）([github.com][1])；
- 支持手动
.close()或使用with上下文管理；
☁️ Azure OpenAI 支持
- 使用
AzureOpenAI类； - 支持
azure_endpoint,azure_deployment,api_version等参数； - API 路径与参数结构可能与标准 API 不完全一致 ([github.com][1])。
END