模型 API
Chat Completions：对话生成
使用 OpenAI 兼容对话接口，配置消息、多轮上下文、输出和流式响应。
更新于
POST
/v1/chat/completions请求结构
POST /v1/chat/completions 使用 messages 数组描述对话。每次请求携带需要保留的历史消息；不要假设上一次请求会自动成为下一次上下文。系统指令应描述稳定的约束，用户消息携带本次任务。
| 参数 | 类型 / 要求 | 说明 |
|---|---|---|
| model | string · required | 目录返回的模型 ID |
| messages | array · required | 非空消息数组，包含 role 与 content |
| stream | boolean · optional | 默认 false；true 返回 SSE |
| temperature | number · model-dependent | 采样参数，部分推理模型不接受 |
| max_tokens / max_completion_tokens | integer · model-dependent | 按照目标模型设置输出预算，不要同时盲目设置 |
cURL
curl --fail-with-body https://api.token4ai.cloud/v1/chat/completions \
-H "Authorization: Bearer $TOKEN4AI_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"model": "YOUR_MODEL_ID",
"messages": [
{
"role": "system",
"content": "Answer concisely."
},
{
"role": "user",
"content": "Explain an API gateway."
}
],
"stream": false
}'读取响应
普通文本通常位于 choices[0].message.content。工具调用位于 message.tool_calls，此时 content 可能为 null。检查 finish_reason 以区分正常结束、长度截断和工具调用，不能只判断 HTTP 200。
usage 描述模型报告的 Token 使用量。不同供应商的缓存、推理 Token 或使用量字段可能不同，应用应容忍可选字段缺失，并以使用历史中的费用记录核对支出。
上下文与兼容性
- 限制消息历史，避免不断重传无用上下文。
- 接入现有 OpenAI 客户端时通常只需替换 base_url 与 API Key，但仍应验证模型参数。
- 结构化输出、多模态和工具能力应逐项测试，不能从文本成功推断。