Create chat completion

Send message history and receive a response or streamed deltas.

200

{
  "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
  }
}

POST /v1/chat/completions

Provide model and a nonempty messages array. For multi-turn conversations, include the relevant history in order; this endpoint does not automatically retain conversation history for the client.

Read the result

Text normally appears in choices[0].message.content. Also check finish_reason: stop is a normal stop, length indicates a limit, and tool_calls requires executing tools and sending results back. Content may be null or empty.

With stream: true, read choices[].delta instead of complete messages. Tool calling, JSON output, and generation-limit parameters depend on the model. Do not assume max_tokens and max_completion_tokens can be set together.

HTTP examples · Python · TypeScript · Streaming

简体中文

Cache and reasoning fields

prompt_cache_key and prompt_cache_retention are conditional upstream hints, not guarantees of cache hits or pinned channels. The current ordinary Chat DTO does not declare top-level prompt_cache_options. Use model-supported reasoning_effort values. Nested reasoning is an alternative input converted by channel dialect; avoid conflicting settings.

Some channels return message.reasoning_content or message.reasoning; distinguish these from final content. Cache and reasoning usage may appear in usage.prompt_tokens_details and completion_tokens_details. These fields can be absent and cannot determine a final invoice.

Added fields verified against revision 30a6d88a4.

Prompt caching · Reasoning · Context management

Sampling, probabilities, and conditional fields

The request DTO represents seed, frequency_penalty, presence_penalty, logit_bias, logprobs, and top_logprobs; model support is still required. Adapters remove some unsupported sampling fields. Non-streaming probabilities appear in choices[].logprobs.content; streaming uses each choice’s logprobs. Forced formatting or protocol conversion does not guarantee preservation of these extra fields.

web_search_options is for Chat models with native search support, not a replacement for Responses tools. PDF content can use type: file with nested file fields, without a general upload API or OCR fallback.

Generation parameters and example · PDF input · Data controls

Audio input and predicted output

messages[].content can include type: input_audio and input_audio: {data, format}, with plain Base64 data and a model supporting audio input. Do not use transcription’s multipart structure. Request-level modalities / audio are model dependent and do not guarantee every conversion path or assistant audio-ID continuation.

prediction is a JSON field ordinary native Chat can forward, commonly {type: content, content: originalText}. It requires model support and currently has no Chat-to-Responses mapping. Still check completion and review generated code before using it.

Audio input example · Prediction example · Video protocol boundaries

Tool policies and JSON mode

tool_choice can request auto, required, none, or a selected function. parallel_tool_calls: false requests at most one function call per turn. See tool controls for protocol shapes, strict conversion limits, and a complete example.

JSON mode requests JSON without a business Schema guarantee. See JSON mode for both protocol shapes and runnable examples.

Authorizations

Authorization · string · header · required

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

Body

application/json

model · string · required

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

Example:

"YOUR_MODEL_ID"

messages · object[] · required

Minimum array length: 1

Show child attributes

stream · boolean · default: 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

Required range: 0 <= x <= 1073741823

max_completion_tokens · integer

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

Required range: 0 <= x <= 1073741823

stop · string string[]

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

tools · object[]

Show child attributes

tool_choice · string object

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

Example:

"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

Response

200

application/json

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

id · string

object · string

Example:

"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