创建对话

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "YOUR_MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 3,
    "total_tokens": 15
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "YOUR_MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 3,
    "total_tokens": 15
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

POST /v1/chat/completions 至少提供 model 和非空 messages。多轮对话时，把需要保留的历史消息按顺序一并发送；此接口不会自动为客户端保存会话历史。

读取结果

文本一般在 choices[0].message.content。同时检查 finish_reason：stop 是正常停止，length 表示达到上限，tool_calls 需要执行工具并回传结果。内容可能为 null 或为空。设置 stream: true 后读取 choices[].delta，不要按完整 message 结构读取。工具调用、JSON 格式及生成上限参数由目标模型决定；不要默认同时设置 max_tokens 和 max_completion_tokens。 HTTP 示例 · Python · TypeScript · 流式输出 Read in English

缓存与推理字段

prompt_cache_key、prompt_cache_retention 是条件支持的上游提示，不是缓存命中或渠道固定承诺。当前普通 Chat DTO 未声明顶层 prompt_cache_options。reasoning_effort 使用模型支持的值；嵌套 reasoning 是按渠道方言转换的另一种输入，不要发送矛盾设置。部分渠道返回 message.reasoning_content 或 message.reasoning，应与最终 content 区分。缓存与推理用量可出现在 usage.prompt_tokens_details 和 completion_tokens_details 中；这些字段可缺失，不能据此计算最终账单。新增字段核对版本：30a6d88a4。提示词缓存 · 推理模型 · 上下文管理

采样、概率与条件字段

seed、frequency_penalty、presence_penalty、logit_bias、logprobs 和 top_logprobs 已在请求 DTO 中表达，仍需模型支持。适配器会移除部分不支持的采样字段。非流式 token 概率在 choices[].logprobs.content；流式位于每个 choice 的 logprobs。渠道强制格式化或协议转换不保证保留这些额外字段。 web_search_options 用于支持原生搜索的 Chat 模型，不能替代 Responses 的 tools。PDF 内容可使用 type: file 与嵌套 file 字段，但没有通用上传 API 或 OCR 回退。生成参数与示例 · PDF 输入 · 数据控制

音频输入与预测输出

messages[].content 可包含 type: input_audio 与 input_audio: {data, format}；data 为纯 Base64，模型必须支持音频输入。不要使用音频转写的 multipart 结构。modalities / audio 请求字段依模型而定，不能保证所有转换路径或助手音频 ID 续聊。 prediction 是普通原生 Chat 可以转发的 JSON 字段，常用 {type: content, content: 原文}。它需要模型支持，当前 Chat → Responses 不映射该字段。非空文本仍需检查完成状态，并在使用生成的代码前审阅。音频输入示例 · 预测输出示例 · 视频协议边界

工具策略与 JSON 模式

tool_choice 可请求 auto、required、none 或指定函数，parallel_tool_calls: false 请求单轮最多一个函数调用。字段形状、strict 转换限制与完整示例见工具控制。 JSON 模式只请求 JSON，不提供业务 Schema 保证；两个协议的字段形状和可运行示例见 JSON 模式。

授权

Authorization

string

header

必填

模型调用 API Key，不是控制台登录凭据 / Model API key, not console login credentials

请求体

application/json

model

string

必填

模型列表返回的原始 ID；需要支持当前接口 / Exact ID from the model list; must support this endpoint

示例:

"YOUR_MODEL_ID"

messages

object[]

必填

Minimum array length: 1

Show child attributes

stream

boolean

默认值:false

是否返回 SSE 事件；取决于模型和渠道支持 / Return SSE events when supported by the model and channel

stream_options

object

仅在 stream=true 时使用 / Use with stream=true

Show child attributes

temperature

number

采样温度；范围、默认值和是否可用由模型决定 / Sampling temperature; range, default, and support depend on the model

top_p

number

核采样；范围、默认值和是否可用由模型决定 / Nucleus sampling; range, default, and support depend on the model

max_tokens

integer

生成上限；模型可能要求更小的值，并限制与其他字段组合 / Output limit; models may impose a smaller limit or parameter restrictions

必填范围: 0 <= x <= 1073741823

max_completion_tokens

integer

生成上限；模型可能要求更小的值，并限制与其他字段组合 / Output limit; models may impose a smaller limit or parameter restrictions

必填范围: 0 <= x <= 1073741823

stop

停止序列；支持情况取决于模型 / Stop sequences; model dependent

tools

object[]

Show child attributes

tool_choice

auto / required / none 或指定函数；Chat 为嵌套 function.name，Responses 为同层 name，需模型支持 / auto / required / none or a selected function; nested function.name in Chat, sibling name in Responses; requires model support

response_format

object

输出格式；json_object / json_schema 需模型支持 / Output format; json_object / json_schema require model support；json_object 只请求 JSON，仍需校验业务字段 / json_object requests JSON only; validate business fields

Show child attributes

prompt_cache_key

string

缓存分组提示；不保证命中、亲和或权限隔离 / Cache grouping hint; no guarantee of hits, affinity, or authorization isolation

prompt_cache_retention

string

缓存保留提示，值依赖上游模型；跨协议转换不保证保留 / Retention hint with model-dependent values; not guaranteed across conversion

reasoning_effort

string

原生 Chat 推理强度；模型名修饰符和转换可影响最终值，需模型支持 / Native Chat reasoning effort; modifiers and conversion can affect the effective value; model support required

示例:

"medium"

reasoning

object

OpenRouter 风格推理输入，按渠道方言转换；不是 Responses reasoning 结构 / OpenRouter-style reasoning input converted by channel dialect; not the Responses reasoning schema

Show child attributes

seed

number

尽力复现的种子；建议整数，不能保证确定性 / Best-effort seed; use integers, not a determinism guarantee

frequency_penalty

number

频率惩罚；范围与支持依模型，显式零保留 / Frequency penalty; model-specific range and support; explicit zero retained

presence_penalty

number

出现惩罚；范围与支持依模型，显式零保留 / Presence penalty; model-specific range and support; explicit zero retained

logprobs

boolean

请求 token 对数概率；模型适配器可能移除 / Request token log probabilities; model adapter may remove it

top_logprobs

integer

候选数；需要 logprobs，范围与实际返回数依模型 / Alternative count; requires logprobs, limits and returned count depend on model

service_tier

string

默认过滤，需渠道允许和上游支持 / Filtered by default; requires channel permission and upstream support

safety_identifier

string

默认过滤，需渠道允许 / Filtered by default; requires channel permission

store

boolean

默认允许；DisableStore 删除字段而非强制 false，不是保留策略保证 / Allowed by default; DisableStore removes rather than forces false; not a retention guarantee

logit_bias

object

以目标 tokenizer 的 token ID 为键，范围依模型 / Target-tokenizer token IDs as keys; model-specific ranges

Show child attributes

web_search_options

object

条件支持的 Chat 原生搜索结构，不是 Responses tools / Conditional native Chat search options, not Responses tools

Show child attributes

prediction

object

原生 Chat 条件支持；转 Responses 当前无映射，不保证加速 / Conditional native Chat support; currently unmapped to Responses; no speedup guarantee

Show child attributes

modalities

string[]

目标输出模态，需模型与路径支持；本例仅文本 / Target output modalities; model/path dependent; example covers text only

audio

object

条件支持的音频输出选项，不是 input_audio 输入内容 / Conditional audio output options, not input_audio content

Show child attributes

parallel_tool_calls

boolean

显式 false 请求单轮最多一个函数调用；模型/渠道条件支持，不调度应用并发 / Explicit false requests at most one function call per turn; model/channel dependent, not application concurrency control

响应

成功响应；stream=true 时返回 SSE，仍需检查终止事件。 / Successful response; stream=true returns SSE; still check terminal events.

string

object

string

示例:

"chat.completion"

created

integer

model

string

choices

object[]

Show child attributes

usage

object

用量字段随上游变化，不是最终账单 / Usage varies by upstream and is not an invoice

Show child attributes

开始使用

接入指南

应用实践

多模态接入

检索与重排

生产与排障

补充协议与任务

API 参考

读取结果

缓存与推理字段

采样、概率与条件字段

音频输入与预测输出

工具策略与 JSON 模式

授权

请求体

响应

​读取结果

​缓存与推理字段

​采样、概率与条件字段

​音频输入与预测输出

​工具策略与 JSON 模式

授权

请求体

响应

读取结果

缓存与推理字段

采样、概率与条件字段

音频输入与预测输出

工具策略与 JSON 模式