对话补全

OpenAI 兼容 /v1/chat/completions 完整参考——请求参数表、模型参数语义（指定或交由智能查询路由自动择优）、响应结构与 usage 计量字段、curl 与响应 JSON 示例

POST /v1/chat/completions 是平台的 OpenAI 兼容统一查询入口：您提交一组对话消息，平台智能研判查询复杂度、择优路由至最合适的模型，再带着生成内容与本次的统一计价词元用量返回。这是日常接入最常用的接口。

本页给出该接口的完整参考：请求参数、模型参数语义、响应结构与 usage 计量字段，以及可直接运行的 curl 与响应示例。

端点

项	值
方法与路径	`POST /v1/chat/completions`
认证	请求头 `Authorization: Bearer <您的 API 密钥>`
内容类型	`Content-Type: application/json`
兼容性	OpenAI Chat Completions 兼容；既有 SDK 大多可直接复用

请求参数

请求体为 JSON，沿用 OpenAI 标准字段。常用参数如下：

参数	类型	必填	说明
`model`	string	是	平台统一中性模型名；亦可填路由别名交由智能查询路由自动择优（见下文「模型参数语义」）
`messages`	array	是	对话消息数组，每条含 `role`（`system` / `user` / `assistant` / `tool`）与 `content`
`stream`	boolean	否	是否流式返回，默认 `false`；为 `true` 时按分片逐段返回，详见流式响应
`temperature`	number	否	采样温度（通常 0~2），越高输出越发散；不传则用模型默认
`top_p`	number	否	核采样阈值（0~1），与 `temperature` 二选其一调节即可
`max_tokens`	integer	否	本次输出的最大统一计价词元数上限；不传则用模型默认上限
`stop`	string / array	否	停止序列，命中即结束生成
`tools`	array	否	可调用工具的声明（函数式工具调用），结构见下文「工具调用」
`tool_choice`	string / object	否	工具选择策略（`auto` / `none` / 指定某工具）
`response_format`	object	否	输出格式约束（如 `{ "type": "json_object" }` 约束为 JSON 输出）
`user`	string	否	您侧的终端用户标识，便于您自行归集与排查（不影响计量归属）

messages 的角色。 system 用于设定助手的行为基调，user 为用户输入，assistant 为模型历史回复（多轮对话时回填），tool 用于回传工具执行结果。多轮对话时请把完整上下文按时序放入 messages。

工具调用

当需要让模型调用外部函数时，在 tools 中声明可用工具，平台按 OpenAI 工具调用约定返回 tool_calls：

字段	说明
`tools[].type`	工具类型，函数式工具为 `function`
`tools[].function.name`	工具名
`tools[].function.description`	工具用途说明，供模型判断何时调用
`tools[].function.parameters`	工具入参的 JSON Schema 声明
`tool_choice`	`auto`（由模型决定）/ `none`（禁用）/ 指定某工具强制调用

模型决定调用工具时，响应的 finish_reason 为 tool_calls，message.tool_calls 中给出待调用的工具与入参；您执行后将结果以 role: "tool" 追加进 messages 再次请求，即可续接生成。

模型参数语义

model 字段支持两种用法，对应平台的两类接入姿态：

用法	`model` 填什么	路由行为
指定模型	平台模型清单中的某个中性模型名	直接路由至该模型；该模型异常时平台仍会按可用性自动重试与切换，对您透明
自动择优	平台提供的路由别名（如统一智能路由名）	平台按本次查询复杂度自动研判，在候选模型中择优转发至最合适的模型

可调用的模型清单与路由别名以模型列表接口实时返回为准，也可在控制台查看。
无论指定还是自动择优，响应中的 model 字段都会回显本次实际路由的模型名，便于您核对。
模型名为平台统一的中性名称，您无需关心其背后的具体来源；平台负责在背后聚合与切换。

何时交由自动择优。 若您的业务查询复杂度参差不齐（既有简单问答又有复杂推理），交由智能查询路由自动择优通常更划算——平台为简单查询选用更轻量的档位、为复杂查询选用更强的档位，兼顾质量与成本。需要确定性模型行为时，再显式指定模型。

响应结构

请求成功后返回标准 OpenAI 兼容的 chat.completion 对象。除生成内容外，usage 字段在标准基础上扩展，携带本次请求的统一计价词元计量信息：

字段	说明
`id`	本次响应的标识
`object`	固定为 `chat.completion`（流式时为 `chat.completion.chunk`）
`created`	响应生成时间戳
`model`	本次实际路由的模型名（回显，可与请求核对）
`choices`	生成结果数组，每项含 `index` / `message` / `finish_reason`
`choices[].message`	助手回复，含 `role` 与 `content`；触发工具调用时含 `tool_calls`
`choices[].finish_reason`	结束原因：`stop`（正常结束）/ `length`（达 `max_tokens`）/ `tool_calls`（待工具调用）/ `content_filter`（被安全护栏处置）
`usage`	本次请求的统一计价词元用量（见下表）

usage 字段

字段	含义
`prompt_tokens`	本次输入的统一计价词元数
`completion_tokens`	本次输出的统一计价词元数
`total_tokens`	输入与输出合计
`cached_input_tokens`	命中上游模型供应商缓存的输入词元数
`price_tier`	本次适用的单价档（6 档计量口径之一）
`thinking`	本次是否走深度推理（thinking）档

计量口径速读。 平台按「输入·缓存命中 / 输入·缓存未命中 / 输出」三类计量项，各自再分 thinking 与 no-thinking 档，合计 6 档统一计价词元口径。缓存命中档的计价更低，thinking（深度推理）档相对溢价；缓存是否命中以上游模型供应商返回为准。各档计量字段与逐条调用记录的完整说明详见用量明细与计量说明。

usage 与逐条记录同源。 响应里的 usage 即本次调用落入用量明细逐条记录的请求侧来源——同一笔用量在响应、用量明细、月度结算单三处口径一致、数字同源，逐项比对都对得上。

完整示例

请求

curl https://<平台入口地址>/v1/chat/completions \
  -H "Authorization: Bearer <您的 API 密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型名>",
    "messages": [
      { "role": "system", "content": "你是一名严谨的企业知识助手。" },
      { "role": "user", "content": "请帮我归纳这段会议纪要的三条关键决议。" }
    ],
    "temperature": 0.3,
    "max_tokens": 512,
    "stream": false
  }'

响应

{
  "id": "<响应标识>",
  "object": "chat.completion",
  "created": 0,
  "model": "<本次实际路由的模型名>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "会议的三条关键决议如下：……"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "cached_input_tokens": 0,
    "price_tier": "<本次适用单价档>",
    "thinking": false
  }
}

工具调用响应（finish_reason 为 tool_calls）

{
  "id": "<响应标识>",
  "object": "chat.completion",
  "model": "<本次实际路由的模型名>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "<工具调用标识>",
            "type": "function",
            "function": {
              "name": "<工具名>",
              "arguments": "{ ... }"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 }
}

收到 tool_calls 后，请在本地执行对应工具，将结果以 role: "tool" 追加进 messages，再次发起请求续接生成。

错误与流式

被安全护栏处置。 当请求或响应触发注入防护、敏感信息脱敏或应拒答拦截时，平台返回结构化护栏处置结果，finish_reason 可能为 content_filter 或返回结构化错误体。护栏能力与误拒说明详见安全防护处置。

流式返回。 将 stream 设为 true 即可边生成边返回，分片形态、usage 末帧与断流重试建议详见流式响应。

各类错误码（400 / 401 / 403 / 404 / 429 / 5xx）与重试建议见错误码与重试。

您想做的	前往
用 Anthropic 兼容形态接入	消息接口
获取可调用模型清单	模型列表
调用前预先核对用量	词元计数
读懂 usage 的 6 档计量	用量明细与计量说明
处理流式与错误	流式响应 · 错误码与重试

端点