Skip to main content
POST
Create Chat Completion
Create a chat completion request. The model generates a response based on the provided message list.
The content field supports the following two forms:Plain text string
Array of objects (for multimodal input)Each element in the array is distinguished by the type field:
image_url and video_url also support passing a string directly, equivalent to the url field in object form:

Parameter Description

Each element in the array has the following fields:When image_url is passed as an object, its fields are:When video_url is passed as an object, its fields are:
Both the object form (url field) and the string shorthand support the following formats:
  • Base64 encoding: data:image/png;base64,... or data:video/mp4;base64,...
  • File reference: ms://<file_id>
See Use the Kimi Vision Model.

Usage Example

Non-streaming Response

Streaming Response

The model name in the response example will be returned based on the model parameter in the request. When using the kimi-k2.6 model, the "model" field in the response will show "kimi-k2.6".
The Kimi API is stateless and does not retain conversation history. To implement multi-turn dialogue, append the previous assistant reply (and any tool results, if applicable) back into the messages array before sending the next request.
When the conversation history grows too long, retain only the most recent messages or compress earlier turns to avoid exceeding the model’s context limit.
Use the response_format parameter to constrain the model output format:
  • {"type": "text"} (default): plain text output
  • {"type": "json_object"}: forces a valid JSON Object output
  • {"type": "json_schema", "json_schema": {...}}: outputs structured data according to the given JSON Schema (Structured Output)
When using json_object, you must explicitly describe the expected JSON fields and types in the system prompt or user prompt, otherwise the model may produce unexpected results.
Pass external tools defined as JSON Schema via the tools parameter. The model can decide to invoke them when appropriate.Request example
tool_calls in the responseWhen finish_reason is "tool_calls", the model returns a tool_calls array containing id, function.name, and function.arguments:
Submitting tool execution resultsAfter executing the tool locally, append the result back into messages using role="tool". The tool_call_id must match the id from the request:
kimi-k2.6 and kimi-k2.7-code support thinking mode: the model first outputs its reasoning process (reasoning_content) before producing the final answer. K3 always reasons and uses the top-level reasoning_effort field (currently only "max").K2.x request parametersResponse fieldsIn non-streaming responses, choices[0].message contains:
When using a thinking model in multi-turn conversations, always preserve the reasoning_content of each historical assistant message in messages, otherwise the model may lose reasoning context.
Set stream: true to enable streaming output. The model returns content incrementally in Server-Sent Events (SSE) format. Recommended for scenarios requiring real-time feedback, such as chat, code generation, and long text output.
SSE Response FormatEach line starts with data:, followed by a JSON object. When finish_reason is null, content accumulates in delta.content; when finish_reason is not null, the output is complete:
stream_optionsUse stream_options: {"include_usage": true} to receive an additional usage field in the last chunk (before data: [DONE]), showing the token consumption of the request:
Partial Mode (Prefill) allows you to prefill an output prefix in the last assistant message of messages, guiding the model to continue generation in the format or direction you expect.How to EnableAppend an role="assistant" message at the end of the messages array, and set partial: true:
The model will continue generating code from ````python\n` instead of outputting explanatory text first.Common Use Cases
  • Force the model to start with a specific format (e.g., JSON’s {, a code block’s ````python`)
  • Maintain role name prefixes in role-play scenarios (combined with the name field)
  • When finish_reason="length", use the same prefix to continue truncated content
Do not mix Partial Mode with response_format={"type": "json_object"}, as this may lead to unexpected model responses. To guide JSON output, use Structured Output directly, or set partial: true and prefill { separately.

Authorizations

Authorization
string
header
required

The Authorization header expects a Bearer token. Use an MOONSHOT_API_KEY as the token. This is a server-side secret key. Generate one on the API keys page in your dashboard.

Body

application/json
model
enum<string>
default:kimi-k3
required

Model ID

Available options:
kimi-k3
messages
(Standard message · object | Dynamic tool message · object)[]
required

A list of Kimi K3 conversation messages. In addition to standard messages, you can insert a {"role": "system", "tools": [...]} message at any conversation position to dynamically load tools. A dynamic tool message omits content and only affects subsequent conversation turns.

A Kimi K3 conversation message. Supports both standard messages and system messages that omit content and declare dynamically loaded tools through tools.

max_tokens
integer
deprecated

Deprecated, please refer to max_completion_tokens

max_completion_tokens
integer

The maximum number of tokens to generate for the chat completion. The default varies by model: for Kimi K3 it defaults to 131072 and can be set up to 1048576. If the result reaches the maximum number of tokens without ending, the finish reason will be "length"; otherwise, it will be "stop". This refers to the length of tokens you expect us to return, not the total length of input plus output. If input plus max_completion_tokens exceeds the model context window, the API returns invalid_request_error.

response_format
object

Controls the model output format. Default is {"type": "text"} for plain text output. Set to {"type": "json_object"} to enable JSON mode, ensuring output is a valid JSON object (you must guide the model to output JSON in the prompt). Set to {"type": "json_schema"} to enable Structured Output, constraining output to match a specified JSON Schema (recommended, requires the json_schema field). If you encounter schema validation issues, please submit feedback at walle GitHub Issues (https://github.com/MoonshotAI/walle/issues).

stop

Stop words, which will halt the output when a full match is found. The matched words themselves will not be output. A maximum of 5 strings is allowed, and each string must not exceed 32 bytes

stream
boolean
default:false

Whether to return the response in a streaming fashion. Default is false.

stream_options
object

Options for streaming responses

tools
object[]

A list of tools the model may call

Maximum array length: 128
prompt_cache_key
string

Used to cache responses for similar requests to optimize cache hit rates. For Coding Agents, this is typically a session id or task id representing a single session; if the session is exited and later resumed, this value should remain the same. For Kimi Code Plan, this field is required to improve cache hit rates. For other agents involving multi-turn conversations, it is also recommended to implement this field

safety_identifier
string

A stable identifier used to help detect users of your application that may be violating usage policies. The ID should be a string that uniquely identifies each user. It is recommended to hash the username or email address to avoid sending any identifying information

tool_choice

Controls whether the model calls tools. auto (default): the model decides whether to call tools; none: no tool calls; required: force a tool call; or pass an object specifying a particular function to force that tool call.

Available options:
auto,
none,
required
reasoning_effort
enum<string>
default:max

Kimi K3 always enables thinking with Preserved Thinking. Thinking effort only supports max.

Available options:
max

Response

Chat completion response

id
string

Unique identifier for the completion

object
string

Object type

Example:

"chat.completion"

created
integer

Unix timestamp of when the completion was created

model
string

Model used for the completion

choices
object[]

List of completion choices

usage
object