API 文档 · 对话模型

OpenAI 兼容接口

POST /v1/chat/completions：请求字段、流式、usage 与错误格式。

POST https://cn-api.aitoken.tools/v1/chat/completions 与 OpenAI Chat Completions 接口兼容。请求体原样转给上游（model 换成上游的模型 ID），响应原样返回（model 换回本站的模型名）。

请求字段

字段	说明
`model`	必填。本站的对话模型名
`messages`	必填，非空数组。支持 system / user / assistant / tool 消息与图片（能力表含 image 时）
`max_tokens / max_completion_tokens`	可选。本次最多输出的 token；不填按模型的最大输出冻结额度，填了更省冻结额
`stream`	可选。true 时返回 SSE 流
`stream_options.include_usage`	可选。流式时在最后一个块里返回 usage
`tools、temperature、top_p、stop…`	其他字段原样转给上游，按上游的规则校验

流式

stream: true 时返回 text/event-stream，每个事件 data: {…}，以 data: [DONE] 结束。平台总会向上游要 usage 用于结算；只有你也传了 stream_options.include_usage 时，带 usage 的最后一个块才会转给你。

失败与重试

上游在返回第一个字节前失败（超时、5xx、限流）：平台自动换下一条线路重试，最多 3 条，你只看到最终结果。
上游判定为请求问题（如 400 参数错误）：原样返回上游的状态码与错误信息，不收费。
流已经开始后中断：不再重试；按已输出的内容结算（见对话计费）。

错误格式

错误体使用 OpenAI 格式 { "error": { "message", "type", "code", "param" } }，官方 SDK 能直接识别。常见状态：

状态	type / code	原因
401	`invalid_api_key`	Key 缺失、错误或已停用
402	`quota_exceeded`	账号或 Key 的额度不足以冻结本次上界
403	`permission_denied`	Key 没有 chat:create，或模型未开通 / 不在 Key 白名单
404	`not_found`	模型名不存在或不是对话模型
422	`invalid_parameter`	请求体不合法（如 messages 为空），param 指出字段
429	`rate_limited`	超过 RPM，或进行中的对话请求超过 50 个；按 Retry-After 等待
503	`no_available_channel`	暂时没有可用线路

Key 无效（401）与超过 RPM（429）在鉴权时就被拦下，错误体是平台通用格式 { "error": { "code", "message", "retryable", "request_id" } }，同样带 error.message，SDK 能正常抛出异常。

curl https://cn-api.aitoken.tools/v1/chat/completions \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Hello" }]
  }'