API 文档

端点说明

参数兼容矩阵（重点）

模型列表

获取可用模型：GET /v1/models

curl -s http://127.0.0.1:8082/v1/models \
  -H "Authorization: Bearer sk-你的Key"

模型会随上游调整，建议始终以 /v1/models 的实时返回为准。

接入建议

原生模式（推荐）

/v1/responses 更接近上游能力，建议新项目优先用这个端点。

curl -s http://127.0.0.1:8082/v1/responses \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-5.1-codex-mini",
    "stream":false,
    "input":[
      {"role":"user","content":[{"type":"input_text","text":"你好，做个自我介绍"}]}
    ]
  }'

curl -N http://127.0.0.1:8082/v1/responses \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-5.1-codex-mini",
    "stream":true,
    "input":[
      {"role":"user","content":[{"type":"input_text","text":"给我三条 Go 调试建议"}]}
    ]
      }'

原生透传模式（可选）

curl -N http://127.0.0.1:8082/v1/responses \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -H "X-Codex-Mode: raw" \
  -d '{
    "model":"gpt-5.3-codex",
    "stream":true,
    "input":[
      {"role":"user","content":[{"type":"input_text","text":"你好"}]}
    ]
  }'

等价开关：X-Codex-Raw-Passthrough: true。

注意：透传模式下不再做自动兼容修正（例如强制 stream、XML tool 协议文本清洗等），调用方需自行处理上游原生行为。

原生 Tools / Function Calling 示例（/v1/responses）

第一轮请求（触发函数调用）：

curl -s http://127.0.0.1:8082/v1/responses \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-5.3-codex",
    "stream":false,
    "input":[
      {"role":"user","content":[{"type":"input_text","text":"请先调用 list(limit=20, offset=0)，再回答我看到多少个工具。"}]}
    ],
    "tools":[
      {
        "type":"function",
        "name":"list",
        "description":"列出可用工具",
        "parameters":{
          "type":"object",
          "properties":{"limit":{"type":"integer"},"offset":{"type":"integer"}},
          "required":["limit","offset"]
        }
      }
    ],
    "tool_choice":{"type":"function","name":"list"}
  }'

第二轮请求（携带 function_call_output 续传）：

{
  "model":"gpt-5.3-codex",
  "stream":false,
  "input":[
    {"type":"message","role":"user","content":[{"type":"input_text","text":"请先调用 list(limit=20, offset=0)，再回答我看到多少个工具。"}]},
    {"type":"function_call","call_id":"call_xxx","name":"list","arguments":"{\"limit\":20,\"offset\":0}"},
    {"type":"function_call_output","call_id":"call_xxx","output":"{\"total\":4,\"tools\":[...]}"} 
  ]
}

OpenAI 兼容模式

通用客户端（文本、流式、基础 tools）可直接使用 /v1/chat/completions。

curl -s http://127.0.0.1:8082/v1/chat/completions \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-5.1-codex-mini",
    "stream":false,
    "messages":[
      {"role":"user","content":"写一个 Go 读取 JSON 的示例"}
    ]
  }'

curl -N http://127.0.0.1:8082/v1/chat/completions \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-5.1-codex-mini",
    "stream":true,
    "messages":[
      {"role":"user","content":"给我一段快速排序伪代码"}
    ]
  }'

Tools / Function Calling 示例（兼容模式）

curl -s http://127.0.0.1:8082/v1/chat/completions \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-5.1-codex-mini",
    "stream":false,
    "messages":[{"role":"user","content":"帮我查上海天气"}],
    "tools":[
      {
        "type":"function",
        "function":{
          "name":"get_weather",
          "description":"查询天气",
          "parameters":{
            "type":"object",
            "properties":{"city":{"type":"string"}},
            "required":["city"]
          }
        }
      }
    ],
    "tool_choice":"auto"
  }'

返回里会包含 choices[0].message.tool_calls（若模型触发了函数调用）。

多模态输入（兼容模式，基础）

curl -s http://127.0.0.1:8082/v1/chat/completions \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-5.1-codex-mini",
    "messages":[
      {
        "role":"user",
        "content":[
          {"type":"text","text":"描述这张图片"},
          {"type":"image_url","image_url":{"url":"https://example.com/demo.png"}}
        ]
      }
    ]
  }'

常见错误

API Key 鉴权与限流错误码

所有 API 请求需在 Authorization 头携带 Bearer sk-xxxx。网关会依次检查 Key 状态、有效期、模型权限、配额、速率和并发。

错误响应格式：

{
  "error": {
    "message": "Rate limit exceeded: too many requests per minute",
    "type": "invalid_request_error",
    "code": "rate_limit_rpm"
  }
}

限流策略说明：

• RPM — 滑动窗口（60秒），内存计数，服务重启后清零
• RPD — 按自然日计数，跨天自动重置
• 并发限制 — 同一 Key 同时处理的请求数上限，请求完成后自动释放
• 单次 Token 限制 — 检查请求体中 max_tokens 和 max_output_tokens，取较大值与限制比较
• 所有限制值为 0 表示不限制，Key 级设置优先于分组级设置

支持与反馈