Create chat completion

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

停止序列；支持情况取决于模型 / 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

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

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

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

Getting started

Integration guides

Application guides

Multimodal guides

Retrieval and reranking

Production and troubleshooting

Additional protocols and tasks

API reference

Create chat completion

Read the result

Cache and reasoning fields

Sampling, probabilities, and conditional fields

Audio input and predicted output

Tool policies and JSON mode

Authorizations

Body

Response

​Read the result

​Cache and reasoning fields

​Sampling, probabilities, and conditional fields

​Audio input and predicted output

​Tool policies and JSON mode

Authorizations

Body

Response

Read the result

Cache and reasoning fields

Sampling, probabilities, and conditional fields

Audio input and predicted output

Tool policies and JSON mode