对话补全

POST /v1/chat/completions — 根据对话历史创建模型响应，支持流式输出、工具调用与多模态输入

根据对话历史创建模型响应。兼容 OpenAI Chat Completions API，支持流式（SSE）与非流式响应、工具调用、多模态输入。

POST/v1/chat/completions

这个接口是做什么的：把它想象成一次「一问一答」的对话请求——你把到目前为止的完整对话内容（messages，包含历史上所有用户和助手的发言）一次性打包发过去，模型基于全部上下文生成下一句回复。每次请求都要带上完整历史，服务端不会帮你记住上一轮说了什么。它是目前最通用、生态最成熟的对话接口，聊天机器人、客服助手、代码助手等绝大多数场景优先选它；如果你需要服务端自动帮你保存多轮历史、或需要更细粒度的推理过程控制，可以看看 Responses。

鉴权：在请求头携带 Authorization: Bearer <令牌>，详见鉴权与令牌。

平台对本端点的请求参数是透传并对齐 OpenAI 官方格式，不会另行定义参数名或参数结构。也就是说，本页参数表以 OpenAI 官方文档当前的字段名和语义为准；官方后续新增、调整或废弃参数时，实际请求行为跟随官方变化。

请求参数

modelstring必填

要调用的模型 ID，如 deepseek-v4-flash、gpt-5.5。可用模型集合以 GET /v2/models 返回为准，具体模型在本端点是否可用以实际请求结果为准

messagesarray

对话历史消息数组，按时间顺序排列，结构见下文「消息结构」。普通对话必填；FIM（中间填充）请求传 prefix/suffix 时可省略（条件必填）

prefixstring

FIM 请求的前缀文本（需模型支持 FIM），传入后 messages 可省略

suffixstring

FIM 请求的后缀文本，配合 prefix 使用（需模型支持）

streamboolean

为 true 时以 SSE 流式返回增量 chunk，见下文「流式输出」

默认值: false

stream_optionsobject

流式选项，仅 stream=true 时有效

max_tokensinteger

官方已标注废弃，被 max_completion_tokens 取代，且与 o 系列推理模型不兼容。仍可用于兼容旧代码，但新代码请改用 max_completion_tokens。超出模型上下文上限时返回参数错误

max_completion_tokensinteger

当前官方推荐字段，替代 max_tokens。限制模型这一轮最多能生成多少 token，包含用户看不到的推理 token（如果模型是推理模型）——因此推理模型实际拿到的「可见回复」长度可能比这个数字小。与 max_tokens 同时传入时本字段优先生效

temperaturenumber

控制生成的随机性，取值 0~2。数值越低输出越确定、越贴近"最可能"的答案，适合信息抽取、分类、代码生成等需要稳定结果的场景；数值在 1 左右适合日常对话；调高会更有创意但也更容易跑偏或答非所问。多数场景不需要特意设置

top_pnumber

核采样阈值，取值 0~1，是 temperature 之外另一种控制随机性的方式。数值越小候选词范围越窄、输出越保守；一般不建议和 temperature 同时调整，挑一个调即可

top_kinteger

Top-K 采样（仅部分模型支持，透传上游）

stopstring | array

停止序列，字符串或最多 4 个字符串组成的数组，模型生成内容命中其中任意一个即停止。官方注明 o3、o4-mini 等最新推理模型不支持此参数

ninteger

生成的候选回复条数，一次请求生成多个候选供你挑选或对比。注意：官方按此惯例值处理，但官方参数说明文字未明写具体默认值；条数越多消耗的 token 和费用也越多，一般场景填 1 即可

默认值: 1

seednumber

随机种子，用于尽量复现相同输出。官方标注为 Beta 功能且已标注废弃，未提供替代字段；即使传入相同 seed，也不保证每次输出完全一致，效果以模型为准（透传上游）

response_formatobject

输出格式约束。type 缺省为 "text"（普通文本）；{"type":"json_schema","json_schema":{...}} 按 JSON Schema 约束结构化输出，官方推荐的做法（需模型支持）；{"type":"json_object"} 只保证输出是合法 JSON、不约束具体结构，官方称其为"较旧的方式"，模型支持 json_schema 时建议优先用后者

toolsarray

工具定义数组，见下文「工具调用」。向不支持工具调用的模型传此参数会返回错误

tool_choicestring | object

工具选择策略："none"、"auto"、"required"，或 {"type":"function","function":{"name":"..."}} 指定工具

默认值: "auto"

parallel_tool_callsboolean

是否允许模型在一次回复中发起多个工具调用

reasoning_effortstring

推理强度档位，仅部分推理模型系列支持（如 gpt-5 系列、o 系列），普通模型传了会被忽略或报错。官方枚举共 7 档：none（几乎不推理，适合语音、快速检索等延迟敏感场景）、minimal、low（工具调用、多步决策等轻量推理）、medium（多数场景的均衡档，兼顾质量与延迟成本）、high（复杂调试、深度规划）、xhigh（深度研究、长周期 agent 任务）、max（最高推理量，用于最复杂任务）。默认值因模型而异，不是统一档位；并非所有模型支持全部 7 档，建议先用 medium 试跑，效果不理想再按需调整

frequency_penaltynumber

频率惩罚，取值 -2~2。数值越大，对已经出现过很多次的词施加的惩罚越重，能减少"翻来覆去说同一句话"的重复问题；数值为负则相反，会鼓励重复。写代码、生成结构化内容时通常不需要调

presence_penaltynumber

存在惩罚，取值 -2~2。数值越大，模型越倾向引入没提过的新内容、避免绕着同一个话题重复表达；数值为负则相反，会让模型更愿意重复已出现的内容。一般不需要设置，写长文或头脑风暴时可以调高一些

logprobsboolean

是否返回输出中每个 token 的对数概率。多用于分析模型对自己输出的\"确信程度\"，普通对话场景不需要开启（需模型支持）

top_logprobsinteger

每个位置额外返回概率最高的 N 个候选 token（0~20），需配合 logprobs 置 true 使用，用于查看模型在该位置还考虑了哪些替代词

userstring

终端用户标识，用于滥用追踪。官方已标注废弃，被 safety_identifier（滥用追踪）与 prompt_cache_key（缓存优化）两个字段拆分取代（透传上游）

prompt_cache_keystring

提示词缓存键，用于提升相似请求的缓存命中率（替代 user 字段，需上游支持）

prompt_cache_retentionstring

提示词缓存保留时长。官方已标注废弃，被 prompt_cache_options.ttl 取代（上游支持时透传）

prompt_cache_optionsobject

提示词缓存的当前推荐配置方式，取代已废弃的 prompt_cache_retention。mode 控制缓存策略（默认按隐式 breakpoint 缓存，设为 "explicit" 可关闭隐式缓存）；ttl 控制缓存最短保留时间（当前仅支持 "30m"），上游支持时生效

verbositystring

控制回复的详略程度，取值 low/medium/high（gpt-5 系列支持）。low 更简洁直接，high 会展开更多说明和上下文，官方默认 medium，上游支持时透传

默认值: "medium"

modalitiesarray

输出模态（如 ["text","audio"]），上游支持时透传

audioobject

音频输出配置（voice、format 等），配合 modalities 使用，上游支持时透传

logit_biasobject

token 偏置映射，调整指定 token 的出现概率，上游支持时透传

metadataobject

附加元数据键值对，上游支持时透传

predictionobject

预测输出内容（Predicted Outputs，加速重复性内容生成），上游支持时透传

web_search_optionsobject

联网搜索配置（search_context_size 等），上游支持时透传

service_tierstring

请求的服务层级，控制处理优先级和延迟/价格权衡，取值 auto/default/flex/scale/priority/fast。未设置时按 auto 处理；具体层级是否可用取决于上游渠道支持情况。注意：设置为 fast 或 priority 时，响应体里的 service_tier 字段会统一显示为 priority

默认值: "auto"

safety_identifier 与 store 两个字段默认被平台过滤，不会透传上游，以保护终端用户隐私。

思考档位说明

reasoning_effort（以及 Responses 接口的 reasoning.effort）等思考参数的档位、默认值与支持范围因模型供应商而异，不存在跨厂商统一的档位标准。上表所列的 7 档语义（none~max）来源于 OpenAI 官方协议规范，并非适配所有供应商——不同供应商对同一档位名的解释、支持的档位子集、甚至参数本身是否存在，都可能不同。

本端点对思考参数做透传：你传的值原样发给上游模型，网关不做翻译或裁剪。因此请以你实际调用的模型的官方参考文档为准，不要跨供应商照抄档位设置。

消息结构

messages 数组中每个消息对象包含以下字段：

rolestring必填

消息角色，常用 system、user、assistant、tool。注意：对 o 系列与 gpt-5 系列模型，平台会将 system 自动改写为上游要求的 developer 角色

contentstring | array必填

消息内容。纯文本直接传字符串；多模态内容传 typed content 数组（见下文）。assistant 消息发起工具调用时可为空字符串

namestring

消息发送者名称，用于区分同角色的多个实体

tool_callsarray

仅 assistant 消息使用。回填模型上一轮返回的工具调用（原样回传）

tool_call_idstring

仅 tool 角色消息必填。对应 tool_calls 中该次调用的 id

多模态输入

content 传数组时，每个元素是带 type 字段的对象：

type	字段	说明
`text`	`text`	文本内容
`image_url`	`image_url.url`、`image_url.detail`	图片。`url` 支持 http(s) URL 与 base64 data URL（`data:image/png;base64,...`）两种；`detail` 取 `low`/`high`/`auto`，缺省按 `high` 处理
`input_audio`	`input_audio.data`、`input_audio.format`	音频。`data` 为 base64 编码，`format` 如 `mp3`、`wav`
`file`	`file.filename` + `file.file_data`，或 `file.file_id`	文件。`file_data` 为 base64 data URL；`file_id` 引用已上传文件
`video_url`	`video_url.url`	视频 URL（视频理解类模型，如阿里百炼系列）

{
  "role": "user",
  "content": [
    { "type": "text", "text": "这张图里有什么？" },
    { "type": "image_url", "image_url": { "url": "https://example.com/pic.png", "detail": "high" } }
  ]
}

多模态输入要求模型具备对应能力（如视觉模型才能处理 image_url）。向不支持多模态的模型发送媒体内容会返回错误。模型能力以 GET /v2/models 的能力标记为准。

请求示例

curl https://api.jimu.chat/v1/chat/completions \
  -H "Authorization: Bearer $JIMU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}],
    "max_completion_tokens": 1024
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["JIMU_API_KEY"],
    base_url="https://api.jimu.chat/v1",
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "你好"}],
    max_completion_tokens=1024,
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.JIMU_API_KEY,
  baseURL: "https://api.jimu.chat/v1",
});

const resp = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "你好" }],
  max_completion_tokens: 1024,
});
console.log(resp.choices[0].message.content);

响应结构

非流式响应示例（实测，推理模型）：

响应200

{
  "id": "58881cdb-747f-4222-b9ea-3e066cc34aab",
  "object": "chat.completion",
  "created": 1785252811,
  "model": "deepseek-v4-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮你？",
        "reasoning_content": "用户打招呼……"
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 16,
    "total_tokens": 21,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 16 },
    "prompt_cache_hit_tokens": 0,
    "prompt_cache_miss_tokens": 5
  },
  "system_fingerprint": "fp_8b330d02d0_prod0820_fp8_kvcache_20260402"
}

关键字段说明：

id：响应 ID，格式不固定（UUID、msg_ 前缀等），不要对格式做假设。
choices[].message：模型生成的消息，role 恒为 assistant。推理模型会额外返回 reasoning_content（思维链）；发起工具调用时携带 tool_calls，此时 content 可能为空字符串，也可能是引导性文字，不要假设它一定为空。
choices[].finish_reason：结束原因，取值 stop（正常结束）、length（达到 token 上限）、tool_calls（发起工具调用）、function_call（旧版函数调用）、content_filter（内容被过滤）。
system_fingerprint：上游系统指纹，可能为 null。
usage：token 计量。权威字段为 prompt_tokens / completion_tokens / total_tokens，是唯一可以写进业务逻辑的计量字段。*_tokens_details 与附加字段（如上例的 prompt_cache_hit_tokens / prompt_cache_miss_tokens）属于上游附加信息，结构不固定，不要依赖其存在或结构。

usage 中还可能出现 input_tokens、output_tokens、input_tokens_details、claude_cache_creation_5_m_tokens、claude_cache_creation_1_h_tokens 等字段，均为保留字段（出现时恒为 0 / null），不要读取或依赖，未来可能移除。计量只认 prompt_tokens / completion_tokens / total_tokens。特别注意：claude_cache_creation_* 不是有效的缓存命中计数，不要拿它计算缓存命中率。

流式输出

设置 "stream": true 后，响应以 Server-Sent Events 返回（Content-Type: text/event-stream）。每个事件为一行 data: {JSON}，事件间以空行分隔；流末尾发送 data: [DONE] 表示结束。

典型 chunk 序列（实测）：

data: {"id":"ab175b3b-...","object":"chat.completion.chunk","created":1785252811,"model":"deepseek-v4-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}

data: {"id":"ab175b3b-...","object":"chat.completion.chunk",...,"choices":[{"index":0,"delta":{"content":"1、2、3"},"finish_reason":null}],"usage":null}

data: {"id":"ab175b3b-...","object":"chat.completion.chunk",...,"choices":[{"index":0,"delta":{"content":""},"finish_reason":"stop"}],"usage":{"prompt_tokens":7,"completion_tokens":32,"total_tokens":39,...}}

data: [DONE]

要点：

首个 chunk 的 delta 携带 role: "assistant"，之后每个 chunk 的 delta.content 是增量文本，拼接即为完整回复。推理模型的思维链增量通过 delta.reasoning_content 下发。
结束 chunk 的 delta 内容为空，finish_reason 给出结束原因。
usage 默认不出现在流式 chunk 中（恒为 null）。传 "stream_options": {"include_usage": true} 后，usage 的携带位置有两种实际形态：追加一个 choices 为空数组的专用 chunk，或直接附在携带 finish_reason 的最后一个内容 chunk 上（如上例）。解析器应读取任何携带非空 usage 的 chunk，不要用 choices 是否为空作为判断条件。
工具调用的流式返回中，delta.tool_calls 按增量分片下发，function.arguments 为逐步累积的 JSON 字符串片段，需自行拼接后解析。
参数类错误（如模型不存在、额度不足）在流建立之前返回，是普通的 JSON 错误响应（HTTP 非 200）。流建立之后若上游中途失败，平台会下发错误事件或直接终止连接（形态取决于上游渠道）。客户端应把「未收到 [DONE] 就结束的流」视为失败，并处理两种出错时机。

工具调用

工具调用是一次「请求 → 执行 → 回填 → 再请求」的往返流程。

1. 在请求中声明工具。 tools 数组每项的结构：

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "查询指定城市天气",
    "parameters": {
      "type": "object",
      "properties": { "city": { "type": "string", "description": "城市名" } },
      "required": ["city"]
    }
  }
}

2. 模型决定调用工具。 响应中 finish_reason 为 tool_calls，message.tool_calls 给出调用参数（实测）：

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "好的！我来查询一下北京的天气情况。",
      "tool_calls": [{
        "index": 0,
        "id": "call_00_9HGXAbXfVL4Bq2XZJFEN8802",
        "type": "function",
        "function": { "name": "get_weather", "arguments": "{\"city\": \"北京\"}" }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

注意：function.arguments 是 JSON 字符串（不是对象），需 JSON.parse 后使用，流式模式下分片下发、拼完整再解析；content 此时可能为空字符串，也可能像上例一样带引导文字；tool_calls[].id 的格式不固定（call_...、toolu_... 等）。

3. 执行工具并回填结果。 在你的系统里执行函数，然后把两条消息追加到 messages：

上一条 assistant 消息原样回填（含 content 与 tool_calls，不要改写）；
一条 role: "tool" 的消息，tool_call_id 对应该次调用的 id，content 为执行结果。

[
  { "role": "user", "content": "北京今天天气如何？" },
  { "role": "assistant", "content": "好的！我来查询一下北京的天气情况。", "tool_calls": [{ "index": 0, "id": "call_00_9HGXAbXfVL4Bq2XZJFEN8802", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\": \"北京\"}" } }] },
  { "role": "tool", "tool_call_id": "call_00_9HGXAbXfVL4Bq2XZJFEN8802", "content": "{\"temp\": 26, \"cond\": \"晴\"}" }
]

4. 再次发起请求。 模型基于工具结果生成最终自然语言回复，finish_reason 为 stop。

用 parallel_tool_calls: true 时模型可能在一次回复中返回多个 tool_calls，需逐个执行并各回一条 tool 消息。tool_choice 可强制使用或禁用工具。

错误情形

错误响应为嵌套 error 对象，HTTP 状态码非 200（实测）：

{
  "error": {
    "code": "model_not_found",
    "message": "模型 xxx 暂无可用渠道，请稍后再试 (request id: 20260728143942943269800tFRTapux)",
    "type": "jimu_api_error"
  }
}

排查时优先读取响应头 X-Jimu-Request-Id 获取请求 ID（成功响应也携带），error.message 末尾的 (request id: ...) 后缀是同一 ID。完整的 type 取值、状态码含义与三种错误形态对照见错误处理与请求追踪。

本端点特有的典型错误：

情形	说明
模型无可用渠道	`code` 为 `model_not_found`，确认模型 ID 拼写与账号可用性
模型不接受 OpenAI 格式	`code` 为 `format_not_accepted`：模型存在，但当前没有接受本端点协议格式的渠道。换用其他模型，或联系平台调整渠道配置
向不支持工具调用的模型传 `tools`	返回参数类错误，模型能力以模型查询接口的能力标记为准
`max_completion_tokens`（或已废弃的 `max_tokens`）超出模型上下文上限	返回参数类错误，按模型实际上限调整
向不支持多模态的模型发送媒体内容	返回参数类错误，换用视觉/多模态模型
流式中途断开	未收到 `[DONE]` 即结束，按失败重试（见「流式输出」）

客户端接入

第三方客户端与积木桌面端的接入指南——base_url 配置、鉴权方式、常见问题，以及积木客户端的一键鉴权。

实时会话

GET /v1/realtime — WebSocket 实时语音对话端点，兼容 OpenAI Realtime API