OpenAI API 调用示例：Chat Completions 实战

本文你将得到什么？

在已完成《OpenAI API 申请》的前提下，学会：

• 用 HTTP 头携带 API Key
• 发送一条对话补全请求
• 解析回复并处理常见错误
• 了解流式输出的基本形态

官方文档：https://platform.openai.com/docs/
控制台：https://platform.openai.com/

下列模型名与路径请以文档当前版本为准，示例侧重「可运行的结构」。

1. 用 curl 快速验证

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "你是简洁的中文助手。"},
      {"role": "user", "content": "用三句话介绍什么是 API。"}
    ],
    "temperature": 0.4
  }'

成功时响应中会包含 choices[0].message.content 字段。把完整 JSON 保存一次，方便对照字段含义。

2. Python 最小示例

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是严谨的技术写作者。"},
        {"role": "user", "content": "列出调用 OpenAI API 前的 5 条安全检查。"},
    ],
    temperature=0.3,
)

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

安装 SDK 前请阅读官方 Docs 的安装说明；版本更新时注意 breaking changes。

3. 消息角色怎么用？

role	用途
system	全局风格、安全边界、输出格式
user	当前用户请求
assistant	历史助手回复（多轮时回传）

多轮时把历史按顺序拼接，但注意上下文长度与费用；过长会话应摘要压缩。

4. 错误处理骨架

import time
from openai import RateLimitError, APIError

def chat_with_retry(client, **kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            time.sleep(2 ** attempt)
        except APIError as e:
            # 记录 status / request id，便于工单排查
            raise
    raise RuntimeError("重试耗尽")

5. 流式输出入门

适合聊天 UI 逐字展示：

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "写一首关于调试的短诗"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

6. 生产环境建议

1. Key 仅存服务端密钥库 / 环境变量
2. 对用户输入做长度与敏感内容策略控制
3. 记录 request id、模型名、耗时、token 用量
4. 为 Prompt 建配置中心，避免魔法字符串
5. 设置预算告警，防止异常循环调用

网页端体验仍可通过 ChatGPT 完成；产品信息见 OpenAI。

7. 常见报错速查

现象	可能原因	处理
401	Key 无效	重新生成并检查环境变量
429	速率/配额	退避重试或降并发
超时	网络或不稳定代理	换网络、加超时与重试
输出截断	max tokens 过小	提高上限或要求更短输出

若必须经代理访问，评估稳定性与合规；镜像站入口 仅为占位，不建议未经评估直接用于生产。

小结

先 curl 打通鉴权，再封装 Python/Node 客户端，最后补齐重试、日志与流式。把《API 申请》里的密钥治理与本文的调用模板结合，即可开始真正的产品集成。更多细节持续以官方 Docs 为准。