OpenAI 兼容 API 调用指南

先选对接口

OpenAI 官方推荐所有新项目优先使用 Responses API；Chat Completions 仍受支持，适合保留既有 messages 与 choices 集成。Embedding、图像、音频和视频拥有独立资源，不能把所有任务都发送到对话端点。本站兼容哪些端点还取决于模型和渠道，先在模型广场确认精确 ID 与端点。

使用 Responses 完成最小调用

本站使用 Authorization: Bearer。Responses 把模型名和输入放入 JSON；以下请求仅在目标模型与渠道支持 /v1/responses 时有效：

Copycurl "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_NAME","input":"只回复：连接成功"}'

Responses 返回类型化的 output items。SDK 的 output_text 适合快速取得简单最终文本，但通用客户端要遍历 output 并按 type 处理消息、工具调用和其他项目，不能假设 output[0] 永远是正文。

兼容旧应用的 Chat Completions

既有应用仍可调用 /v1/chat/completions，正文通常位于 choices[0].message.content，并读取 finish_reason 与 usage。不要只把 Chat 路径替换为 Responses：input/output、工具结果、多轮续接和流式事件都不同。

Copycurl "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_NAME","messages":[{"role":"user","content":"只回复：连接成功"}]}'

多轮状态与上下文

Responses 可用 previous_response_id 续接，但顶层 instructions 不会自动继承，应在后续轮次重发。历史输入仍会计费并占用上下文，不等于免费无限记忆。需要自行控制数据保存时，应明确存储策略并保存协议要求的完整 output items。

工具调用由应用闭环

自定义函数流程是：声明工具、接收调用、服务端验证名称与参数、执行受控操作、回传结果、继续获取答案。模型生成的 JSON 不是可信授权。文件、网络、金额和收件人必须重新校验，并设置超时、幂等、最小权限和人工确认。

流式解析与完成条件

Responses 与 Chat 都可通过 SSE 流式返回，但事件结构不同。按空行读取完整 event/data，容忍未知事件类型，并以协议定义的完成事件为准；不要把任意 TCP 分片直接交给 JSON 解析器。流式结束时保存停止原因和可能的错误事件；用量字段是否出现及是否需要显式开启，必须按端点和渠道核验。

错误、限流与重试

401 检查密钥、组织或 IP 限制；本站或具体资源的 404 需检查路径与模型；429 可能来自临时速率、余额或消费上限；5xx 才通常属于临时服务故障。临时 429 优先遵循 Retry-After，否则使用带抖动的指数退避，并限制次数与总时长。失败请求也可能占用速率预算，立即无限重试会放大故障。

用量、安全与兼容边界

保存响应 usage，长输入在发送前预估 token，并为用户设置最大输出、速率与费用上限。API Key 只放在服务端秘密管理器，泄露后立即撤销轮换。本站不保证实现 OpenAI 的每个 beta 字段；结构化输出、推理强度、并行工具、图像输入、存储和缓存都要用目标模型做字段级契约测试。