Chat Completions API
Create a chat completion: send messages to Kimi models and get replies, with streaming, tool calling, and vision input.
Content Field Description
Content Field Description
content field supports the following two forms:Plain text stringtype 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:image_url is passed as an object, its fields are:video_url is passed as an object, its fields are:url field) and the string shorthand support the following formats:- Base64 encoding:
data:image/png;base64,...ordata:video/mp4;base64,... - File reference:
ms://<file_id>
Usage Example
Response Format
Response Format
Context Caching (Cache Write)
Context Caching (Cache Write)
prompt_cache_options to control cache write behavior:- The cache is isolated per organization (org); caches are never shared across organizations.
- When a request with the same prefix hits the cache within its lifetime, the cache entry is refreshed with its original TTL. Cache hits are billed only at the cache read price, with no additional cache write charge.
- Cache writes are billed per TTL tier; see Pricing for details.
- Manual cache clearing is not supported; cached prefixes expire automatically after at least 5 minutes of inactivity.
- Explicit cache breakpoints are not supported: the request is rejected (HTTP 400) if
prompt_cache_breakpointappears incontent.
usage.prompt_tokens is always the total number of input tokens. Its internal breakdown is returned in prompt_tokens_details:cached_tokens, cache_write_tokens, and the uncached remainder are mutually exclusive and sum to prompt_tokens; the uncached remainder = prompt_tokens − cached_tokens − cache_write_tokens.For streaming requests, the full cache read/write breakdown is only returned in the usage field of the final chunk (set stream_options.include_usage=true). The Chat Completions response does not echo the applied mode/ttl (unlike the Responses API); keep track of the values used at request time.Multi-turn Conversations
Multi-turn Conversations
messages array before sending the next request.JSON Mode
JSON Mode
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)
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.Tool Use
Tool Use
tools parameter. The model can decide to invoke them when appropriate.Request exampletool_calls in the responseWhen finish_reason is "tool_calls", the model returns a tool_calls array containing id, function.name, and function.arguments:messages using role="tool". The tool_call_id must match the id from the request:Thinking Mode and Preserved Thinking
Thinking Mode and Preserved Thinking
kimi-k3 always reasons and uses the top-level reasoning_effort field ("low", "high", or "max"; default "max"). 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.K2.x request parameterschoices[0].message contains:Streaming
Streaming
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.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
Partial Mode
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:- 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
namefield) - When
finish_reason="length", use the same prefix to continue truncated content
Authorizations
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.
Headers
A client-generated random nonce (a UUID v4 is recommended). Sending it enables Request Signature: the Kimi API returns Msh-Request-Timestamp and Msh-Request-Signature in the response headers, which can later be used to prove that the request was handled by the Kimi API. Exactly one non-empty header value is allowed; if the value is invalid, the request proceeds normally but the headers above are not returned. See Verify Request Signature.
1"7d929748-0ae6-41c2-ab5d-a186498ad721"
Body
- kimi-k3
- kimi-k2.7-code
- kimi-k2.6
Model ID
kimi-k3 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.
- Standard message
- Dynamic tool message
Whether to return log probabilities of the output tokens. If true, the log probability of each output token is returned in the logprobs field of the response message.
An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true when this parameter is used.
0 <= x <= 20Configuration for a Predicted Output, which can greatly improve response times when large parts of the model response are known ahead of time (for example, regenerating a file with only minor changes).
Deprecated, please refer to max_completion_tokens
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.
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 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
Whether to return the response in a streaming fashion. Default is false.
Options for streaming responses
A list of tools the model may call
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
Context cache write options. When omitted, cache write is enabled by default (5m tier): the system automatically writes the request prefix to the 5m cache tier
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
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.
auto, none, required Kimi K3 always enables thinking with Preserved Thinking. Reasoning effort supports low, high, and max, with max as the default.
low, high, max