Skip to main content
POST
创建聊天补全
创建一个对话补全请求,模型将根据输入的消息列表生成回复。
content 字段支持以下两种形式:纯文本字符串
对象数组(用于多模态输入)数组中每个元素通过 type 字段区分类型:
其中 image_urlvideo_url 也支持直接传入字符串,效果等同于对象形式中的 url 字段:

参数说明

数组中每个元素的字段说明如下:image_url 传入对象时,其字段说明如下:video_url 传入对象时,其字段说明如下:
无论使用对象形式(url 字段)还是字符串简写,均支持以下两种格式:
  • base64 编码:data:image/png;base64,...data:video/mp4;base64,...
  • 文件引用:ms://<file_id>
详见使用 Kimi 视觉模型

调用示例

非流式响应

流式响应

响应示例中的模型名称会根据请求中的 model 参数返回。当使用 kimi-k2.6 模型时,响应中的 "model" 字段将显示为 "kimi-k2.6"
Kimi API 是无状态的,本身不具有记忆功能。要实现多轮对话,需在每次请求时把前一轮的 assistant 回复(以及工具执行结果,如适用)原样追加到 messages 数组中再发送。
当对话历史过长时,建议只保留最近的若干条消息,或做消息压缩,以避免超出模型的上下文长度限制。
通过 response_format 参数可约束模型输出格式:
  • {"type": "text"}(默认):普通文本输出
  • {"type": "json_object"}:强制输出合法 JSON Object
  • {"type": "json_schema", "json_schema": {...}}:按给定 JSON Schema 输出结构化数据(Structured Output)
使用 json_object 时,必须在 system prompt 或 user prompt 中明确描述期望的 JSON 字段和类型,否则模型可能输出不符合预期的结果。
通过 tools 参数传入 JSON Schema 定义的外部工具,模型可决定在适当时机调用它们。请求示例
响应中的 tool_callsfinish_reason"tool_calls" 时,模型返回 tool_calls 数组,包含 idfunction.namefunction.arguments
提交工具执行结果在本地执行工具后,将结果通过 role="tool" 消息追加到 messages 中(tool_call_id 必须与请求中的 id 对应):
kimi-k3 始终进行推理,使用顶层 reasoning_effort(支持 "low""high""max",默认 "max")。kimi-k2.6kimi-k2.7-code 支持思考模式,模型在输出最终答案前会先输出推理过程(reasoning_content)。K2.x 请求参数响应字段非流式响应中,choices[0].message 包含:
多轮对话中若使用思考模式,请务必将每一轮 assistant 消息的 reasoning_content 原样保留在 messages 中,否则模型可能丢失推理上下文。
设置 stream: true 可启用流式输出,模型会以 Server-Sent Events (SSE) 格式逐段返回生成的内容。推荐在聊天、代码生成、长文本输出等实时性要求高的场景中使用。
SSE 响应格式每一行以 data: 开头,内容为 JSON 对象。当 finish_reasonnull 时,内容在 delta.content 中累加;当 finish_reason 不为 null 时,表示输出结束:
stream_options通过 stream_options: {"include_usage": true} 可在最后一个 chunk(data: [DONE] 之前)额外获取 usage 字段,显示本次请求的 Token 消耗:
Partial Mode(Prefill)允许你在 messages 的最后一条 assistant 消息中预填输出前缀,从而引导模型按照你期望的格式或方向继续生成。开启方式messages 数组末尾添加一条 role="assistant" 的消息,并设置 partial: true
模型会从 ````python\n` 之后继续生成代码,而不是先输出解释文字再写代码。常见用途
  • 强制模型以特定格式开头(如 JSON 的 {、代码块的 ````python`)
  • 角色扮演中保持角色名称前缀(配合 name 字段)
  • finish_reason="length" 时,用相同的前缀续写被截断的内容
请勿将 Partial Mode 与 response_format={"type": "json_object"} 混用,否则可能获得预期外的模型回复。如需引导 JSON 输出,建议直接使用 Structured Output 或单独设置 partial: true 并预填 {

授权

Authorization
string
header
必填

Authorization 请求头需要一个 Bearer 令牌。使用 MOONSHOT_API_KEY 作为令牌。这是一个服务端密钥,请在 API 密钥页面 生成。

请求体

application/json
model
enum<string>
默认值:kimi-k3
必填

模型 ID

可用选项:
kimi-k3
messages
(标准消息 · object | 动态工具消息 · object)[]
必填

Kimi K3 对话消息列表。除标准消息外,还可在任意对话位置插入 {"role": "system", "tools": [...]} 消息动态加载工具;该动态工具消息不包含 content 字段,并且只影响后续对话。

Kimi K3 对话消息。既支持标准消息,也支持不含 content、通过 tools 声明动态工具的 system 消息。

logprobs
boolean
默认值:false

是否返回输出 Token 的对数概率。设置为 true 时,在响应 message 的 logprobs 字段中返回每个输出 Token 的对数概率信息

top_logprobs
integer

指定在每个 Token 位置返回概率最高的候选 Token 数量(0-20),各候选 Token 附带对数概率。使用此参数时必须将 logprobs 设置为 true

必填范围: 0 <= x <= 20
prediction
object

Predicted Output 配置。当模型响应的大部分内容可以提前预知时(例如重新生成仅有少量修改的文件),可显著降低响应延迟

max_tokens
integer
已弃用

已弃用,请使用 max_completion_tokens

max_completion_tokens
integer

聊天补全生成的最大 Token 数量。默认值因模型而异:Kimi K3 默认为 131072,最大可设置为 1048576。如果结果达到最大 Token 数而未结束,finish reason 将为 "length";否则为 "stop"。此值为期望返回的 Token 长度,而非输入加输出的总长度。如果输入加 max_completion_tokens 超出模型上下文窗口,将返回 invalid_request_error。

response_format
object

控制模型输出格式。默认值为 {"type": "text"},即纯文本输出。设置为 {"type": "json_object"} 可启用 JSON 模式,确保输出为合法 JSON 对象(需在 prompt 中引导模型输出 JSON 并指定格式)。设置为 {"type": "json_schema"} 可启用 Structured Output,按指定的 JSON Schema 约束输出结构(推荐,需配合 json_schema 字段使用)。如果您在使用 JSON Schema 时遇到校验问题,欢迎到 walle GitHub Issues (https://github.com/MoonshotAI/walle/issues) 提交反馈。

stop

停用词,完全匹配时将停止输出。匹配到的词本身不会被输出。最多允许 5 个字符串,每个不超过 32 字节

stream
boolean
默认值:false

是否以流式方式返回响应,默认 false

stream_options
object

流式响应选项

tools
object[]

模型可调用的工具列表

prompt_cache_key
string

用于缓存相似请求的响应以优化缓存命中率。对于 Coding Agent,通常是代表单个会话的 session id 或 task id;退出并恢复会话时应保持不变。对于 Kimi Code Plan,此字段为必填以提高缓存命中率。对于其他多轮对话 Agent,也建议使用此字段

safety_identifier
string

用于检测可能违反使用政策的用户的稳定标识符。应为唯一标识每个用户的字符串。建议对用户名或邮箱进行哈希处理以避免发送可识别信息

tool_choice

控制模型是否调用工具。auto(默认):模型自行决定是否调用工具;none:不调用工具;required:强制调用工具;也可传入特定函数对象强制调用指定工具。

可用选项:
auto,
none,
required
reasoning_effort
enum<string>
默认值:max

Kimi K3 始终启用思考,并开启 Preserved Thinking。推理强度支持 low、high 和 max,默认为 max。

可用选项:
low,
high,
max

响应

聊天补全响应

id
string

补全结果的唯一标识符

object
string

对象类型

示例:

"chat.completion"

created
integer

补全创建时的 Unix 时间戳

model
string

用于补全的模型

choices
object[]

补全选项列表

usage
object