ChatCompletions 格式
- 与 OpenAI Chat Completions 完全兼容，是最通用的对话入口
- 流式与非流式是同一个接口，区别只在请求体的
stream字段 - 默认流式返回，收到
data: [DONE]结束；传stream: false则一次返回完整结果
认证
所有接口均使用 Bearer Token 进行认证。
获取 API Key：访问控制台 创建。
请求时在请求头中添加：
``http
Authorization: Bearer YOUR_OAIRoute_KEY
``
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
``http
Authorization: Bearer YOUR_OAIRoute_KEY
``
请求参数
模型 ID。可先调用模型列表接口获取当前可用清单。
对话消息数组，按时间顺序排列。每个元素的结构见下列字段。
消息角色。取值 system 系统提示、user 用户输入、assistant 模型回复、tool 工具返回。
消息正文。多模态时可传内容块数组，元素含 type 与对应字段。
参与者名称，用于区分同一角色下的多个说话人。
role 为 tool 时必填，指向对应的工具调用 ID。
是否流式返回。默认 true，以 SSE 事件流逐块返回；传 false 则一次返回完整响应。两种模式共用同一套参数，只有响应形态不同。
是否在流的最后追加一条 usage 统计。
采样温度，取值 0 到 2。数值越低输出越确定。
核采样阈值，取值 0 到 1。建议不要与 temperature 同时调整。
生成的最大 token 数。不同模型的上限不同，超出会被截断。
停止标记。命中其一即结束生成，且标记本身不计入输出。
存在惩罚，取值 -2 到 2。正值鼓励引入新话题。
频率惩罚，取值 -2 到 2。正值抑制重复用词。
随机种子。相同种子与相同参数结果相近，但不保证完全一致。
可用工具清单，结构与 OpenAI 一致。
固定为 function。
函数名，模型会以此为标识发起调用。
函数用途说明。写得越清楚，模型选错的概率越低。
参数的 JSON Schema。
工具选择策略。auto 由模型决定，none 禁止调用，也可指定某个函数。
输出格式约束。text 为普通文本，json_object 要求返回合法 JSON。
生成几条候选回复，默认 1。流式下固定为 1。
终端用户标识，用于按用户维度的统计与风控。
The model ID. Call the models list endpoint first to get the currently available list.
The array of chat messages, in chronological order. Each element's structure is described by the fields below.
The message role. One of system for the system prompt, user for user input, assistant for model replies, or tool for tool results.
The message body. For multimodal input, pass an array of content blocks, each with a type and the matching field.
A participant name, used to distinguish several speakers within the same role.
Required when role is tool; points to the corresponding tool call ID.
Whether to stream. Defaults to true, returning an SSE event stream; pass false to get the complete response in one shot. Both modes share the same parameters; only the response shape differs.
Whether to append a usage summary at the end of the stream.
Sampling temperature, from 0 to 2. Lower values make output more deterministic.
Nucleus sampling threshold, from 0 to 1. Avoid adjusting it together with temperature.
Maximum tokens to generate. Limits differ by model; exceeding them truncates the output.
Stop markers. Generation ends when any one is hit, and the marker itself isn't counted as output.
Presence penalty, from -2 to 2. Positive values encourage new topics.
Frequency penalty, from -2 to 2. Positive values discourage repeated wording.
Random seed. The same seed and parameters give similar results, though not guaranteed identical.
The list of available tools, structured as in OpenAI.
Always function.
The function name; the model uses it to identify which function to call.
A description of what the function does. The clearer it is, the less often the model picks wrong.
The JSON Schema for the parameters.
The tool selection strategy. auto lets the model decide, none forbids calls, or name a specific function.
Output format constraint. text is plain text; json_object requires valid JSON.
How many candidate replies to generate. Defaults to 1; fixed to 1 when streaming.
An end-user identifier, for per-user statistics and abuse control.
响应
stream: false 时返回单个完整对象，choices[].message 一次给全；stream: true 时返回 SSE 事件流，每个事件是一个 chat.completion.chunk，choices[].delta 只带增量。
本次请求的唯一标识。
流式为 chat.completion.chunk，非流式为 chat.completion，可按它判断该按哪种结构解析。
生成时间戳，Unix 秒。
实际使用的模型。
候选回复数组。
候选序号，从 0 开始。
流式增量对象，每个事件只带变化的部分，正文在 delta.content。非流式下不出现。
非流式完整回复，含 role 与 content，替代流式里的 delta。
结束原因。stop 正常结束，length 触达长度上限，tool_calls 发起工具调用，content_filter 被内容策略拦截。流式下在最后一个事件出现。
输入 token 数。
输出 token 数。
两者之和。
With stream: false you get one complete object and choices[].message holds the whole reply. With stream: true the response is an SSE event stream: each event is a chat.completion.chunk and choices[].delta carries only the increment.
A unique identifier for this request.
chat.completion.chunk when streaming, chat.completion otherwise; use it to decide which shape to parse.
Generation timestamp, in Unix seconds.
The model actually used.
The array of candidate replies.
The candidate index, starting at 0.
The streaming delta object; each event carries only the changed part, with the text in delta.content. Absent when not streaming.
The complete reply when not streaming, with role and content; it replaces delta.
Why generation ended. stop is normal, length hit the token limit, tool_calls means a tool call was issued, content_filter means content was blocked. In streaming it appears on the final event.
Input token count.
Output token count.
The sum of both.
流式返回示例
不传 stream 或传 stream: true 时，服务端以 SSE 逐块推送。每块是一个 chat.completion.chunk，正文在 delta.content 里，按顺序拼起来就是完整回复。
data: {"id":"chatcmpl-01KA","object":"chat.completion.chunk","created":1763088289,"model":"YOUR_MODEL_ID","choices":[{"index":0,"delta":{"role":"assistant","content":"你"},"finish_reason":null}]}
data: {"id":"chatcmpl-01KA","object":"chat.completion.chunk","created":1763088289,"model":"YOUR_MODEL_ID","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}
data: {"id":"chatcmpl-01KA","object":"chat.completion.chunk","created":1763088289,"model":"YOUR_MODEL_ID","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]每条 data: 后是一个完整 JSON，行与行之间以空行分隔。收到 data: [DONE] 表示流已结束，此时不要再等待更多数据。
Omit stream or set it to true and the server pushes SSE chunks. Each chunk is a chat.completion.chunk whose text lives in delta.content; concatenated in order they form the full reply.
data: {"id":"chatcmpl-01KA","object":"chat.completion.chunk","created":1763088289,"model":"YOUR_MODEL_ID","choices":[{"index":0,"delta":{"role":"assistant","content":"你"},"finish_reason":null}]}
data: {"id":"chatcmpl-01KA","object":"chat.completion.chunk","created":1763088289,"model":"YOUR_MODEL_ID","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}
data: {"id":"chatcmpl-01KA","object":"chat.completion.chunk","created":1763088289,"model":"YOUR_MODEL_ID","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]Each data: line is a complete JSON object, separated by blank lines. Receiving data: [DONE] means the stream is over; don't keep waiting for more data.
非流式返回示例
传 stream: false 时一次返回完整对象，正文在 choices[0].message.content，object 为 chat.completion。适合后台任务、批处理与结构化抽取，不必处理分块拼装。
{
"id": "chatcmpl-01KA040M0HP1GJWBJYZMKX1XS1",
"object": "chat.completion",
"created": 1763088289,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "你好！有什么可以帮你的？"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 12,
"total_tokens": 21
}
}非流式需要等模型输出完才返回，长文本时客户端等待更久。对首字延迟敏感的聊天界面建议用流式，其余场景用非流式更省事。
With stream: false you get one complete object, with the text in choices[0].message.content and object set to chat.completion. It suits background jobs, batch processing and structured extraction, with no chunk assembly to handle.
{
"id": "chatcmpl-01KA040M0HP1GJWBJYZMKX1XS1",
"object": "chat.completion",
"created": 1763088289,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "你好！有什么可以帮你的？"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 12,
"total_tokens": 21
}
}Non-streaming returns only after the model has finished, so long outputs mean a longer client wait. Use streaming for latency-sensitive chat UIs and non-streaming elsewhere.
支持的模型列表
想按上下文长度、价格或能力标签挑选模型，可查阅 模型列表元数据接口，或直接读取 GET /api/pricing。
To pick models by context length, price, or capability tags, see the models list metadata endpoint, or read GET /api/pricing directly.
流式与非流式怎么选
两种模式的数据一样，区别在传输节奏与等待方式。按场景选即可，不需要为它换接口或换 SDK。
| 场景 | 推荐 | 关键构造 |
|---|---|---|
| 聊天界面、需要首字尽快出现 | 流式 | 不传 stream，逐块渲染 delta.content |
| 后台任务、批量处理 | 非流式 | 传 "stream": false，直接读 message.content |
| 结构化抽取、要解析 JSON | 非流式 | stream: false + response_format 为 json_object |
| 边收边展示、最后再落库 | 流式 | 拼接 delta 得到全文后写入 |
Both modes carry the same data; they differ in pacing and in how long you wait. Pick per scenario — you never switch endpoints or SDKs for it.
| Scenario | Recommended | Key structure |
|---|---|---|
| Chat UIs that need the first token fast | Streaming | Omit stream and render delta.content as it arrives |
| Background jobs and batch processing | Non-streaming | Pass "stream": false and read message.content |
| Structured extraction that parses JSON | Non-streaming | stream: false plus response_format set to json_object |
| Show first, persist later | Streaming | Concatenate delta into the full text, then write it |
使用示例
以下几种最常见的用法都基于同一个接口，差别只在 messages 的构造方式和 stream 参数。完整可复制的请求体见右侧代码栏，切换上方的场景页签即可对应查看。
| 场景 | 关键构造 | 对应右栏页签 |
|---|---|---|
| 基础对话<span class="cell-sub">单轮问答、摘要、翻译</span> | 只放一条 role: user 的消息 | 基础对话 |
| 系统提示词<span class="cell-sub">设定模型身份与输出约束</span> | 在 messages 最前面加一条 role: system | 系统提示词 |
| 多轮对话<span class="cell-sub">需要模型接上文回答</span> | 把历史消息按时间顺序整体放进 messages | 多轮对话 |
| 流式输出<span class="cell-sub">聊天界面等首字要快</span> | 不传或传 "stream": true，响应变为 SSE 事件流 | 流式输出 |
| 非流式输出<span class="cell-sub">一次性拿到完整结果</span> | 传 "stream": false，直接读 choices[0].message.content | 非流式输出 |
| 工具调用<span class="cell-sub">让模型调用你自己的函数</span> | 传 tools 声明函数，模型返回 tool_calls | 函数调用 |
| 结构化输出<span class="cell-sub">要求返回可解析的 JSON</span> | 设置 response_format 为 json_object | 结构化输出 |
| 图片输入<span class="cell-sub">让模型看图回答</span> | content 传内容块数组，含 image_url | 图片输入 |
接口本身不保存会话状态，每一轮都要把完整历史重新提交。历史越长，每轮消耗的输入 token 越多，长期会话建议在客户端做摘要，只保留最近若干轮加一份摘要。
The usages below all hit the same endpoint; only how you build messages and the stream parameter differ. For full copy-ready request bodies see the code panel on the right; switch the scenario tabs above to see each.
| Scenario | Key structure | Matching panel tab |
|---|---|---|
| Basic chat<span class="cell-sub">Single-turn Q&A, summaries, translation</span> | One message with role: user | Basic chat |
| System prompt<span class="cell-sub">Set the model's identity and output constraints</span> | Prepend a role: system message to messages | System prompt |
| Multi-turn chat<span class="cell-sub">The model must answer in context</span> | Put the full history into messages in chronological order | Multi-turn chat |
| Streaming output<span class="cell-sub">Chat UIs that need the first token fast</span> | Omit or set "stream": true; the response becomes an SSE event stream | Streaming output |
| Non-streaming output<span class="cell-sub">Get the complete result in one shot</span> | Pass "stream": false and read choices[0].message.content directly | Non-streaming output |
| Tool calling<span class="cell-sub">Let the model call your own functions</span> | Declare functions in tools; the model returns tool_calls | Tool calling |
| Structured output<span class="cell-sub">Require parseable JSON back</span> | Set response_format to json_object | Structured output |
| Image input<span class="cell-sub">Let the model look at an image</span> | Pass an array of content blocks including image_url | Image input |
The endpoint keeps no session state; every turn must resubmit the full history. The longer the history, the more input tokens each turn consumes, so for long sessions summarize client-side and keep only the last few turns plus a summary.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 参数格式错误，或模型不支持某个字段 |
| 401 | authentication_error | Key 缺失或无效 |
| 402 | payment_required | 余额不足 |
| 429 | rate_limit_error | 触发限流，降低并发或稍后重试 |
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Malformed parameters, or the model doesn't support a field |
| 401 | authentication_error | Key missing or invalid |
| 402 | payment_required | Insufficient balance |
| 429 | rate_limit_error | Rate limit hit; lower concurrency or retry later |