Chat Completions

OpenAI 兼容的对话接口。一个端点路由所有模型，ZeroFA 根据 model 将请求分发到对应上游，并统一 messages 结构、采样参数和 SSE 协议。

POSThttps://zerofa.ai/v1/chat/completions

请求参数

Header 参数

Authorizationstring必填

API Key，格式为 Bearer <key>。

示例：Bearer sk-zerofa-xxx

Content-Typestring必填

示例：application/json

Body 参数application/json

modelstring必填

目标模型，可在下方查看可用模型。切换模型只需修改这一字段。

示例：claude-sonnet-4-6

messagesarray必填

对话历史。每项包含 role 与 content；role 可为 system、user、assistant 或 tool。content 可为字符串或多模态 content parts 数组。

示例：[{"role":"user","content":"hi"}]

streamboolean可选

true 使用 SSE 流式返回；false 一次性返回，默认为 false。

示例：false

temperaturenumber 0–2可选

采样温度，默认 1.0；数值越高，输出越发散。

示例：1.0

top_pnumber 0–1可选

核采样参数，默认 1.0。通常与 temperature 二选一调整。

示例：1.0

max_tokensinteger可选

输出 token 上限；留空时使用模型默认值。

示例：1024

stopstring | string[]可选

停止序列，命中后截断输出。

tools / tool_choicearray / string|object可选

函数调用参数，详见下方“函数调用”。所有上游均可使用。

response_formatobject可选

JSON 模式或结构化输出；OpenAI 协议上游原生支持。

reasoning_effortstring可选

low、medium 或 high，用于控制推理模型的思考强度。

示例：medium

userstring可选

透传业务侧用户标识，便于审计。

示例

{
  "model": "claude-sonnet-4-6",
  "messages": [
    {
      "role": "user",
      "content": "你好，介绍一下你自己"
    }
  ],
  "stream": false,
  "temperature": 1,
  "max_tokens": 1024
}

路由到 OpenAI 协议上游时，请求体会原样透传，n、seed、logprobs 和 stream_options 等原生字段均可生效；Claude 或 Gemini 等跨协议上游会按能力转换。

函数调用（Function Calling）

按 OpenAI 格式传入 tools 与 tool_choice 即可。Claude 和 Gemini 请求会自动转换为厂商原生格式，响应再转换回 tool_calls；支持流式、非流式和多轮工具结果。

请求 · tools

{
  "model": "claude-sonnet-4-6",
  "messages": [{"role": "user", "content": "北京天气怎么样？"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询某城市的实时天气",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

当模型决定调用工具时，finish_reason 为 tool_calls，并在 message.tool_calls 中返回调用信息。

响应 · tool_calls

"message": {
  "role": "assistant",
  "content": "",
  "tool_calls": [{
    "id": "call_abc",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"city\":\"北京\"}"
    }
  }]
}

执行工具后，将结果作为 role: tool 消息并携带 tool_call_id，与上一条 assistant tool_calls 一同传回，模型即可继续回答。

多模态（图像输入）

messages[].content 可使用 content parts 数组，混合 text 与 image_url。图像支持 data URL 或公网 URL，Claude 和 Gemini 协议会自动转换。

请求 · 图像

{
  "model": "gpt-5.4-mini",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "这张图里有什么？"},
      {"type": "image_url",
       "image_url": {"url": "data:image/png;base64,..."}}
    ]
  }]
}

模型是否支持视觉，请查看模型卡片的 Vision 能力标记。

流式响应（SSE）

stream: true 时返回 text/event-stream。每个 chunk 使用一行 data: {...}，并以 data: [DONE] 结束。

event-stream

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"你好"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

可用模型

所有对话模型均可使用此接口，切换模型只需修改 model。完整列表和价格见模型广场，也可以通过 GET /v1/models 获取。

常见错误

完整说明见错误码与计费。最常见的错误包括：

400 model_not_allowed — model 不存在或当前 plan 不允许
402 insufficient_credits — 钱包余额不足
429 rate_limited — RPM 或日额度超限，或上游服务繁忙
503 upstream_unavailable — 所有上游失败（少见）

返回响应

200 OKapplication/json

idstring必填

本次补全请求 id。

objectstring必填

对象类型。

示例：chat.completion

createdinteger必填

Unix 秒级时间戳。

modelstring必填

实际使用的模型 id。

choicesarray必填

候选回复列表，常用字段包括 message、finish_reason 和 index。

usageobject可选

Token 用量统计，包括 prompt_tokens、completion_tokens 和 total_tokens。

响应示例

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1715961234,
  "model": "claude-sonnet-4-6",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "你好！我是……" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 64,
    "total_tokens": 76
  }
}

请求与响应体

用下面的示例确认请求格式与返回结构。需要在线发起请求时，点击页面顶部“调试”拉起在线运行面板。

curl https://zerofa.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "你好，介绍一下你自己"}
    ]
  }'

响应 · 200

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1715961234,
  "model": "claude-sonnet-4-6",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "你好！我是……" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 64,
    "total_tokens": 76
  }
}