Skip to main content
POST
Create a model response
tools supports four tool types: function, namespace, custom (only apply_patch), and web_search. Other types are not supported. The first three run on your side: the model returns a call request, you execute it and send the result back. web_search runs on the server side, with nothing for you to handle.Function callingPass functions defined with JSON Schema through tools, and the model decides when to call them:
When the model decides to call a function, output contains a function_call item whose arguments is a JSON string:
After running it locally, append the previous output to input as is, followed by a function_call_output item (its call_id must match the function_call), and send the next request:
Web searchAdd {"type": "web_search"} to tools. The server first decides from the input whether a search is needed, then runs it and injects the results into the model context, and the model answers from those results:
When a search ran, a web_search_call item appears at the front of output. Add web_search_call.action.sources to include to get the web pages the search hit:

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.

Headers

X-Msh-Request-Nonce
string

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.

Minimum string length: 1
Example:

"7d929748-0ae6-41c2-ab5d-a186498ad721"

Body

application/json
model
string
required

ID of the model to use. This endpoint currently supports kimi-k3.

Example:

"kimi-k3"

input
required

Input for this request. A string is equivalent to a single user message. An array holds ordered typed items and may contain conversation history, tool calls, and tool results.

instructions
string

Top-level system instructions, applied ahead of every input item.

stream
boolean
default:false

When true, the response is delivered as a stream of SSE events.

max_output_tokens
integer

Maximum number of tokens to generate for this response. For kimi-k3 it defaults to 131072 and can be set up to 1048576. This refers to the length of tokens you expect us to return, not the total length of input plus output. When the limit is reached, status is incomplete and incomplete_details.reason is max_output_tokens.

reasoning
object

Reasoning configuration.

text
object

Output text configuration.

tools
(Function tool · object | Custom tool · object | Namespace tool · object | Web search tool · object)[]

List of tools the model may call.

A tool definition, discriminated by type. Supported types are function, custom (only apply_patch), namespace, and web_search; other tool types are not supported.

tool_choice
enum<string>

Controls tool-calling behavior. With auto, the model decides whether to call a tool.

Available options:
auto
include
enum<string>[]

Additional fields to return. Only effective when the web_search tool is used. web_search_call.action.sources returns the web pages the search hit; web_search_call.results returns image search results.

Available options:
web_search_call.results,
web_search_call.action.sources
prompt_cache_key
string

Context cache identifier. Reusing the same value across a session improves cache hit rate.

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

Response

The response was created

A single model response.

id
string

Unique identifier of the response.

Example:

"resp_68f0c1c2d3e4f5a6b7c8d9e0"

object
enum<string>
Available options:
response
created_at
integer

Unix timestamp of when the response was created.

completed_at
integer | null

Unix timestamp of when the response finished. Present when status is completed or incomplete; null when status is in_progress or failed.

status
enum<string>

Response status. The opening snapshot of a stream is in_progress.

Available options:
in_progress,
completed,
incomplete,
failed
model
string

Model that produced the response.

output
(Reasoning · object | Message · object | Function call · object | Custom tool call · object | Web search call · object)[]

The output item array, ordered as web_search_call (if any), reasoning, message, tool calls.

An element of the output array, discriminated by type.

usage
object | null

Token usage for this response.

incomplete_details
object | null

Reason the response is incomplete.

error
object | null

Error information when status is failed.

instructions
string | null
reasoning
object | null
text
object | null
tools
(Function tool · object | Custom tool · object | Namespace tool · object | Web search tool · object)[] | null

A tool definition, discriminated by type. Supported types are function, custom (only apply_patch), namespace, and web_search; other tool types are not supported.

tool_choice
enum<string> | null

Controls tool-calling behavior. With auto, the model decides whether to call a tool.

Available options:
auto
max_output_tokens
integer | null
temperature
number | null
top_p
number | null
metadata
object | null
parallel_tool_calls
boolean
service_tier
string | null
store
boolean

Always false.

background
boolean | null

Always false.

previous_response_id
string | null

Always null.

conversation
object | null

Always null.