什么是 OpenAI 兼容 API？统一接入 GPT、Claude、DeepSeek 的完整指南
OpenAI 兼容 API 指第三方服务按照 OpenAI SDK 熟悉的 HTTP 路径、鉴权方式和 JSON 结构提供接口。开发者只需替换 base_url 和 model，就能把原来调用 OpenAI 的代码迁移到统一网关。它不是“所有模型完全相同”，工具调用、视觉、推理参数仍可能存在差异，因此上线前要做能力测试。
请求字段可对照 OpenAI Chat Completions API 官方参考；本文只描述兼容层的通用行为，不代表所有模型支持全部参数。
兼容层至少需要什么
| 能力 | 标准路径/字段 | 用途 |
|---|---|---|
| 模型列表 | GET /v1/models | 发现可用模型和权限 |
| 对话 | POST /v1/chat/completions | 文本、多轮消息、工具调用 |
| 鉴权 | Authorization: Bearer <key> | 验证 API Key |
| 非流式响应 | choices[0].message.content | 一次性返回答案 |
| 流式响应 | stream: true、SSE data: | 实时显示生成内容 |
| 用量 | usage.prompt_tokens 等 | 统计 Token 与费用 |
ClawSocket 提供统一的 OpenAI 兼容入口：https://api.clawsocket.com/v1。模型名称必须使用控制台列出的 API ID，而不是网页上的品牌宣传名。
最小请求示例
export OPENAI_API_KEY="你的 ClawSocket API Key"
curl https://api.clawsocket.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"messages": [{"role": "user", "content": "用一句话解释 API 兼容"}],
"temperature": 0.2
}'典型响应中应包含 id、choices 和可选的 usage。生产程序不要假设 content 永远是字符串；涉及工具调用时应先判断 tool_calls。
用 OpenAI SDK 迁移
原有 Python 代码通常只需修改两处：
from openai import OpenAI
client = OpenAI(
api_key="你的 ClawSocket API Key",
base_url="https://api.clawsocket.com/v1",
)
answer = client.chat.completions.create(
model="deepseek-v4",
messages=[
{"role": "system", "content": "你是严谨的技术助手"},
{"role": "user", "content": "给出 Python 重试策略"},
],
)
print(answer.choices[0].message.content)Node.js、Go、Java 等语言也可使用各自的 OpenAI 兼容客户端，只要能自定义 HTTP Base URL。对于不兼容 OpenAI 格式的原生 Anthropic 客户端，应使用其专用协议或由网关完成协议转换。
流式输出与错误处理
stream = client.chat.completions.create(
model="gpt-5",
messages=[{"role": "user", "content": "写一段流式输出说明"}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content or ""
print(delta, end="", flush=True)建议按状态码分类：401 重新检查 Key，400 修正请求字段，404 检查 /v1 和模型 ID，429 采用指数退避，5xx 在有限次数内重试。记录服务端 request id 便于向 ClawSocket 支持团队定位。
兼容性测试矩阵
| 测试项 | GPT | Claude | DeepSeek/Kimi/GLM |
|---|---|---|---|
| 多轮文本 | 必测 | 必测 | 必测 |
| 长上下文 | 检查限制 | 检查限制 | 依模型而定 |
| JSON 输出 | 验证 schema | 验证 schema | 验证 schema |
| 图片输入 | 依模型 | 依模型 | 依模型 |
| Function calling | 必测 | 可能需要适配 | 依模型 |
| 流式响应 | 必测 | 必测 | 必测 |
FAQ
OpenAI 兼容 API 等于 OpenAI 官方 API 吗？
不等于。它复用常见协议以降低迁移成本，服务商、模型能力、数据处理和价格都可能不同，生产上线前必须阅读网关条款并完成测试。
为什么同一段代码换模型后报参数错误？
模型对 temperature、JSON schema、工具调用和视觉字段的支持不完全一致。先按兼容性矩阵逐项关闭高级参数，再根据模型文档恢复。
如何在一个入口调用多个模型？
保持 base_url 不变，只切换 model。ClawSocket 负责路由和鉴权，应用侧可根据任务类型选择模型。
OpenAI SDK 能否直接调用 Claude 原生 API？
只有在网关提供 OpenAI 格式适配时才可以。需要 Anthropic 原生消息格式的功能时，应使用 Anthropic SDK 并配置对应的 Base URL。
在ClawSocket API 控制台查看可用模型、Key 和用量；如果你正在改造旧项目，可先阅读OpenAI base_url 配置教程。