API 参考
对话接口
使用 OpenAI 兼容协议进行对话生成，支持普通响应、流式响应和工具调用。
对话接口根据消息列表生成模型回复。请求遵循 OpenAI Chat Completions 协议，支持普通 JSON 响应；目标模型支持时，也支持 SSE 流式输出和工具调用。
接口地址
POST /v1/chat/completions以下兼容入口使用相同的请求结构：
POST /v2/chat/completionsPOST /api/v3/chat/completions
鉴权
Authorization: Bearer <APIQIK_API_KEY>
Content-Type: application/json不要在浏览器、移动端或公开仓库中暴露 API Key。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型标识，以模型目录或 GET /v1/models 返回值为准。 |
messages | array | 是 | 按对话顺序排列的消息列表。 |
temperature | number | 否 | 控制输出随机性，网关接受范围为 0 到 2；具体效果取决于模型。 |
max_tokens | integer | 否 | 限制本次输出 Token 数，必须为 1 到 1000000 的整数。 |
stream | boolean | 否 | 设为 true 时返回 SSE 增量事件。 |
stop | string 或 array | 否 | 命中停止序列后结束生成，是否支持取决于模型。 |
tools | array | 否 | 提供模型可以调用的工具定义。 |
tool_choice | string 或 object | 否 | 控制模型是否以及如何选择工具。 |
response_format | object | 否 | 请求 JSON 等结构化输出，需目标模型支持。 |
user | string | 否 | 终端用户标识。 |
消息结构
{
"role": "user",
"content": "请解释什么是 API 智能路由。"
}role 常用值为 system、user、assistant 和 tool。content 可以是文本；多模态内容和工具字段需由目标模型支持。工具结果消息必须通过 tool_call_id 关联对应的工具调用。
请求示例
curl "${BASE_URL}/v1/chat/completions" \
-H "Authorization: Bearer ${APIQIK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.1",
"messages": [
{"role": "system", "content": "你是一名简洁、可靠的中文助手。"},
{"role": "user", "content": "请解释什么是 API 智能路由。"}
],
"temperature": 0.7,
"max_tokens": 512
}'普通响应
{
"id": "chatcmpl-apiqik-example",
"object": "chat.completion",
"created": 1789987200,
"model": "glm-5.1",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "API 智能路由会根据模型能力和渠道状态选择推理路径。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 24,
"completion_tokens": 27,
"total_tokens": 51
}
}客户端通常读取 choices[0].message.content。finish_reason 可能为 stop、length 或 tool_calls；usage 用于记录输入、输出和总 Token 用量。
流式响应
请求中设置 "stream": true 后，响应为 text/event-stream。客户端必须按 SSE 事件解析，不能按 TCP 数据包边界解析 JSON。
data: {"id":"chatcmpl-apiqik-example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"API"}}]}
data: [DONE]增量文本位于 choices[].delta.content。收到 data: [DONE] 或连接结束后，客户端再合并完整文本；流式响应可能在结束事件中返回用量信息。
工具调用
模型返回 finish_reason: "tool_calls" 时，应用应执行 tool_calls 中声明的函数，再把结果作为 role: "tool" 消息追加到下一次请求。工具定义和参数必须按目标模型支持的 JSON Schema 提供。
错误处理
400：请求体无效、缺少model或messages，或参数超出网关允许范围。401：API Key 缺失或无效。403：API Key 没有调用该模型或能力的权限。429：请求频率或账户额度受限。500、502或503：网关或上游模型服务异常。
客户端应优先依据 HTTP 状态码和结构化错误字段处理失败，并保留响应中的 X-Request-Id 以便排查。