对话接口 POST /v1/chat/completions

最常用的接口，兼容 OpenAI Chat Completions。

请求

curl https://api.token.heimatianqi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-heima-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "system", "content": "你是简洁的助手。"},
      {"role": "user", "content": "用一句话解释什么是 Token。"}
    ],
    "temperature": 0.7,
    "max_tokens": 256,
    "stream": false
  }'

字段	必填	说明
model	是	平台公开模型名（控制台「模型与价格」里复制）
messages	是	对话数组，支持 system / user / assistant / tool
stream	否	true 时以 SSE 逐块返回
max_tokens	否	输出上限；直接影响费用，建议显式设置
temperature / top_p	否	采样参数，按上游支持情况透传
tools / tool_choice	否	工具调用，需模型与上游支持
response_format	否	结构化输出，需模型与上游支持

响应

最小可运行示例（本地验证用）

curl -s "${HEIMA_BASE_URL:-https://api.token.heimatianqi.com/v1}/chat/completions" \
  -H "Authorization: Bearer $HEIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"mock-chat","messages":[{"role":"user","content":"验证对话接口"}],"max_tokens":16}' \
  | python3 -c "import json,sys; d=json.load(sys.stdin); assert d.get('choices'), 'no choices'; print('finish_reason:', d['choices'][0].get('finish_reason'))"

这段在平台自带测试模型上运行，用来确认鉴权、路由、返回结构三件事都正常。

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1790990000,
  "model": "deepseek-v4-flash",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "..."}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 33, "completion_tokens": 42, "total_tokens": 75}
}

usage 是计费依据：输入按输入价、缓存命中部分按缓存价、输出按输出价。

流式返回

stream: true 时返回 text/event-stream，每行形如 data: {...}，最后以 data: [DONE] 结束。 客户端需按 SSE 逐块解析；stream_options: {"include_usage": true} 可在流末尾拿到用量。

错误

HTTP	典型原因	处理
400	请求体不合法（缺 messages、字段类型错误）	按报错字段修正
401	Key 无效/被禁用	换用有效 Key
403	该 Key 无此模型权限；或未实名调用需实名模型；或来源被临时限制	见「错误码与限流」
429	触发限流/渠道容量已满	稍后重试（响应里有 Retry-After 时可参考）
5xx	上游异常	带 request id 反馈；平台侧会记录渠道错误

常见问题

• 能不能像 OpenAI 一样传 n / logprobs？ 取决于上游支持程度，平台会透传； 上游不支持时可能报 400。
• 为什么响应里的模型名和请求不一样？ 平台可能把公开名映射到上游真实型号（详情页会标注来源）。