请求参数
Header 参数
Authorizationstring必填API Key，格式为 Bearer <key>。
示例：
Bearer sk-zerofa-xxxContent-Typestring必填示例：
application/jsonBody 参数application/json
modelstring必填目标模型，可在下方查看可用模型。切换模型只需修改这一字段。
示例：
your-chat-model-idmessagesarray必填对话历史。每项包含 role 与 content；role 可为 system、user、assistant 或 tool。content 可为字符串或多模态 content parts 数组。
示例：
[{"role":"user","content":"hi"}]streamboolean可选true 使用 SSE 流式返回；false 一次性返回，默认为 false。
示例：
falsetemperaturenumber 0–2可选采样温度，默认 1.0；数值越高，输出越发散。
示例：
1.0top_pnumber 0–1可选核采样参数，默认 1.0。通常与 temperature 二选一调整。
示例：
1.0max_tokensinteger可选输出 token 上限；留空时使用模型默认值。
示例：
1024stopstring | string[]可选停止序列，命中后截断输出。
tools / tool_choicearray / string|object可选函数调用参数，详见下方“函数调用”。所有上游均可使用。
response_formatobject可选JSON 模式或结构化输出；OpenAI 协议上游原生支持。
reasoning_effortstring可选low、medium 或 high，用于控制推理模型的思考强度。
示例：
mediumuserstring可选透传业务侧用户标识，便于审计。
示例
{
"model": "your-chat-model-id",
"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": "your-chat-model-id",
"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": "your-chat-model-id",
"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.completioncreatedinteger必填Unix 秒级时间戳。
modelstring必填实际使用的模型 id。
choicesarray必填候选回复列表，常用字段包括 message、finish_reason 和 index。
usageobject可选Token 用量统计，包括 prompt_tokens、completion_tokens 和 total_tokens。
响应示例
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1715961234,
"model": "your-chat-model-id",
"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": "your-chat-model-id",
"messages": [
{"role": "user", "content": "你好，介绍一下你自己"}
]
}'响应 · 200
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1715961234,
"model": "your-chat-model-id",
"choices": [{
"index": 0,
"message": { "role": "assistant", "content": "你好！我是……" },
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 64,
"total_tokens": 76
}
}