对话补全

POST /v1/chat/completions 是生成文本、代码或结构化 JSON 的主要端点，兼容 OpenAI Chat Completions API 的请求与响应结构。

注意

DeepToken 负责渠道路由、优先级、故障转移、Token 统计和配额结算。客户端只需使用规范模型 ID 发起请求。

端点信息

URL：https://api.deeptoken.app/v1/chat/completions
方法：POST
请求头：
- Authorization: Bearer <DEEPTOKEN_API_KEY>（必填）
- Content-Type: application/json（必填）
- X-DeepToken-Org: <ORG_SLUG>（可选，将费用归因到指定组织）

代码示例

选择常用接入方式查看完整请求：

curl https://api.deeptoken.app/v1/chat/completions \
  -H "Authorization: Bearer $DEEPTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "为什么天空是蓝色的？"
      }
    ],
    "temperature": 0.7
  }'

请求参数

请求体为 JSON 对象，常用字段如下：

参数	类型	是否必填	说明
`model`	`string`	是	要调用的规范模型 ID，可在模型目录中查询。
`messages`	`array`	是	对话历史消息列表，结构见下方消息对象。
`temperature`	`number`	否，默认 `1`	取值通常为 `0` 到 `2`。值越高输出越随机，越低越稳定。
`top_p`	`number`	否，默认 `1`	核采样参数。通常不建议同时大幅调整 `temperature` 和 `top_p`。
`stream`	`boolean`	否，默认 `false`	为 `true` 时通过 Server-Sent Events（SSE）逐步返回结果。
`max_tokens`	`integer`	否	限制本次补全最多生成的 Token 数。
`stop`	`string` 或 `array`	否	遇到指定序列时停止生成，最多可传多个停止序列。
`response_format`	`object`	否	可请求 JSON 对象或模型支持的结构化输出格式。
`tools`	`array`	否	模型可调用的工具或函数定义。
`tool_choice`	`string` 或 `object`	否	控制工具调用策略，例如 `none`、`auto`、`required` 或指定工具。

消息对象

messages 数组中的每个对象包含：

字段	类型	是否必填	说明
`role`	`string`	是	消息角色：`system`、`user`、`assistant` 或 `tool`。
`content`	`string` 或 `array`	是	消息内容；多模态模型可使用内容分段数组。
`name`	`string`	否	参与者名称，用于区分同一角色下的多个来源。
`tool_call_id`	`string`	工具响应时需要	当前 `tool` 消息对应的工具调用 ID。

响应结构

非流式请求成功时返回类似以下 JSON：

{
  "id": "chatcmpl-9A8b9C...",
  "object": "chat.completion",
  "created": 1718029562,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "天空呈蓝色主要是因为瑞利散射……"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 85,
    "total_tokens": 98
  }
}

响应字段

id：本次对话补全的唯一标识。
object：对象类型，通常为 chat.completion。
created：创建响应时的 Unix 时间戳，单位为秒。
model：本次请求使用的规范模型 ID。
choices：补全结果列表。
- message：模型生成的消息。
- finish_reason：停止原因，例如 stop、length 或 tool_calls。
usage：本次请求的 Token 用量统计。

重要

DeepToken 会结合实际 Token 用量和计价倍率完成结算。客户端如需展示成本或配额，请以控制台使用记录和钱包流水为最终依据，不要仅使用本地估算。

流式响应

设置 "stream": true 后，服务端通过 SSE 返回多个 chat.completion.chunk 事件。客户端应持续读取 choices[].delta，直到收到结束标记，并正确处理连接中断和超时。

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "user", "content": "列出三个网关监控指标"}
  ],
  "stream": true
}

流式请求同样会写入使用记录，并在请求结束后按真实用量结算。对于中途取消的请求，仍可能产生已经由上游处理的 Token 和相应费用。