curl --request POST \
--url https://api.moonshot.ai/v1/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "kimi-k3",
"input": "<string>",
"text": {},
"tools": [
{
"type": "function",
"name": "<string>",
"description": "<string>",
"parameters": {},
"strict": true
}
]
}
'import requests
url = "https://api.moonshot.ai/v1/responses"
payload = {
"model": "kimi-k3",
"input": "<string>",
"text": {},
"tools": [
{
"type": "function",
"name": "<string>",
"description": "<string>",
"parameters": {},
"strict": True
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'kimi-k3',
input: '<string>',
text: {},
tools: [
{
type: 'function',
name: '<string>',
description: '<string>',
parameters: {},
strict: true
}
]
})
};
fetch('https://api.moonshot.ai/v1/responses', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.moonshot.ai/v1/responses",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'kimi-k3',
'input' => '<string>',
'text' => [
],
'tools' => [
[
'type' => 'function',
'name' => '<string>',
'description' => '<string>',
'parameters' => [
],
'strict' => true
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.moonshot.ai/v1/responses"
payload := strings.NewReader("{\n \"model\": \"kimi-k3\",\n \"input\": \"<string>\",\n \"text\": {},\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {},\n \"strict\": true\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.moonshot.ai/v1/responses")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"kimi-k3\",\n \"input\": \"<string>\",\n \"text\": {},\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {},\n \"strict\": true\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.moonshot.ai/v1/responses")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"kimi-k3\",\n \"input\": \"<string>\",\n \"text\": {},\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {},\n \"strict\": true\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "resp_68f0c1c2d3e4f5a6b7c8d9e0",
"object": "response",
"created_at": 123,
"completed_at": 123,
"status": "in_progress",
"model": "<string>",
"output": [
{
"type": "reasoning",
"id": "rs_68f0c1c2d3e4f5a6b7c8d9e0",
"summary": [
{
"type": "summary_text",
"text": "<string>"
}
],
"encrypted_content": "<string>",
"status": "in_progress"
}
],
"usage": {
"input_tokens": 123,
"input_tokens_details": {
"cached_tokens": 123,
"cache_write_tokens": 123
},
"output_tokens": 123,
"output_tokens_details": {
"reasoning_tokens": 123
},
"total_tokens": 123
},
"incomplete_details": {
"reason": "max_output_tokens"
},
"error": {
"code": "<string>",
"message": "<string>"
},
"instructions": "<string>",
"reasoning": {},
"text": {},
"tools": [
{
"type": "function",
"name": "<string>",
"description": "<string>",
"parameters": {},
"strict": true
}
],
"tool_choice": "auto",
"max_output_tokens": 123,
"temperature": 123,
"top_p": 123,
"metadata": {},
"parallel_tool_calls": true,
"service_tier": "<string>",
"store": true,
"background": true,
"previous_response_id": "<string>",
"conversation": {}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}Responses API
Creates a model response. Provide text or image inputs to generate text or JSON outputs. Have the model call the function tools you define, or use server-side web search.
curl --request POST \
--url https://api.moonshot.ai/v1/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "kimi-k3",
"input": "<string>",
"text": {},
"tools": [
{
"type": "function",
"name": "<string>",
"description": "<string>",
"parameters": {},
"strict": true
}
]
}
'import requests
url = "https://api.moonshot.ai/v1/responses"
payload = {
"model": "kimi-k3",
"input": "<string>",
"text": {},
"tools": [
{
"type": "function",
"name": "<string>",
"description": "<string>",
"parameters": {},
"strict": True
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'kimi-k3',
input: '<string>',
text: {},
tools: [
{
type: 'function',
name: '<string>',
description: '<string>',
parameters: {},
strict: true
}
]
})
};
fetch('https://api.moonshot.ai/v1/responses', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.moonshot.ai/v1/responses",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'kimi-k3',
'input' => '<string>',
'text' => [
],
'tools' => [
[
'type' => 'function',
'name' => '<string>',
'description' => '<string>',
'parameters' => [
],
'strict' => true
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.moonshot.ai/v1/responses"
payload := strings.NewReader("{\n \"model\": \"kimi-k3\",\n \"input\": \"<string>\",\n \"text\": {},\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {},\n \"strict\": true\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.moonshot.ai/v1/responses")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"kimi-k3\",\n \"input\": \"<string>\",\n \"text\": {},\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {},\n \"strict\": true\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.moonshot.ai/v1/responses")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"kimi-k3\",\n \"input\": \"<string>\",\n \"text\": {},\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {},\n \"strict\": true\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "resp_68f0c1c2d3e4f5a6b7c8d9e0",
"object": "response",
"created_at": 123,
"completed_at": 123,
"status": "in_progress",
"model": "<string>",
"output": [
{
"type": "reasoning",
"id": "rs_68f0c1c2d3e4f5a6b7c8d9e0",
"summary": [
{
"type": "summary_text",
"text": "<string>"
}
],
"encrypted_content": "<string>",
"status": "in_progress"
}
],
"usage": {
"input_tokens": 123,
"input_tokens_details": {
"cached_tokens": 123,
"cache_write_tokens": 123
},
"output_tokens": 123,
"output_tokens_details": {
"reasoning_tokens": 123
},
"total_tokens": 123
},
"incomplete_details": {
"reason": "max_output_tokens"
},
"error": {
"code": "<string>",
"message": "<string>"
},
"instructions": "<string>",
"reasoning": {},
"text": {},
"tools": [
{
"type": "function",
"name": "<string>",
"description": "<string>",
"parameters": {},
"strict": true
}
],
"tool_choice": "auto",
"max_output_tokens": 123,
"temperature": 123,
"top_p": 123,
"metadata": {},
"parallel_tool_calls": true,
"service_tier": "<string>",
"store": true,
"background": true,
"previous_response_id": "<string>",
"conversation": {}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}Examples
Examples
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.ai/v1",
)
response = client.responses.create(
model="kimi-k3",
instructions="You are Kimi, an AI assistant provided by Moonshot AI.",
input="Explain context caching in one sentence.",
)
print(response.output_text)
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.MOONSHOT_API_KEY,
baseURL: "https://api.moonshot.ai/v1",
});
const response = await client.responses.create({
model: "kimi-k3",
instructions: "You are Kimi, an AI assistant provided by Moonshot AI.",
input: "Explain context caching in one sentence.",
});
console.log(response.output_text);
curl https://api.moonshot.ai/v1/responses \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $MOONSHOT_API_KEY" \
--data '{
"model": "kimi-k3",
"instructions": "You are Kimi, an AI assistant provided by Moonshot AI.",
"input": "Explain context caching in one sentence."
}'
Tool Use
Tool Use
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:{
"model": "kimi-k3",
"input": "What is the weather in Beijing today?",
"tools": [
{
"type": "function",
"name": "get_weather",
"description": "Get the weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
]
}
output contains a function_call item whose arguments is a JSON string:{
"type": "function_call",
"id": "fc_IrcmDq5JNO0JhWdEpsuZnL9J",
"status": "completed",
"call_id": "get_weather_0",
"name": "get_weather",
"arguments": "{\"city\":\"Beijing\"}"
}
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:{
"model": "kimi-k3",
"input": [
{"type": "message", "role": "user", "content": "What is the weather in Beijing today?"},
{"type": "function_call", "call_id": "get_weather_0", "name": "get_weather", "arguments": "{\"city\":\"Beijing\"}"},
{"type": "function_call_output", "call_id": "get_weather_0", "output": "Sunny, 25°C"}
],
"tools": [
{
"type": "function",
"name": "get_weather",
"description": "Get the weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
]
}
{"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:{
"model": "kimi-k3",
"input": "What are the top news stories today?",
"tools": [
{"type": "web_search"}
]
}
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:{
"type": "web_search_call",
"id": "ws_dackjbcdo9rs73fo3oig",
"status": "completed",
"action": {
"type": "search",
"query": "top news September 3 2026",
"sources": [
{"type": "url", "url": "https://example.com/news/1", "title": "News headline"}
]
}
}
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
ID of the model to use. This endpoint currently supports kimi-k3.
"kimi-k3"
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.
Top-level system instructions, applied ahead of every input item.
When true, the response is delivered as a stream of SSE events.
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 configuration.
Show child attributes
Show child attributes
Output text configuration.
Show child attributes
Show child attributes
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.
- Function tool
- Custom tool
- Namespace tool
- Web search tool
Show child attributes
Show child attributes
Controls tool-calling behavior. With auto, the model decides whether to call a tool.
auto 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.
web_search_call.results, web_search_call.action.sources Context cache identifier. Reusing the same value across a session improves cache hit rate.
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.
Unique identifier of the response.
"resp_68f0c1c2d3e4f5a6b7c8d9e0"
response Unix timestamp of when the response was created.
Unix timestamp of when the response finished. Present when status is completed or incomplete; null when status is in_progress or failed.
Response status. The opening snapshot of a stream is in_progress.
in_progress, completed, incomplete, failed Model that produced the response.
The output item array, ordered as web_search_call (if any), reasoning, message, tool calls.
An element of the output array, discriminated by type.
- Reasoning
- Message
- Function call
- Custom tool call
- Web search call
Show child attributes
Show child attributes
Token usage for this response.
Show child attributes
Show child attributes
Reason the response is incomplete.
Show child attributes
Show child attributes
Error information when status is failed.
Show child attributes
Show child attributes
A tool definition, discriminated by type. Supported types are function, custom (only apply_patch), namespace, and web_search; other tool types are not supported.
- Function tool
- Custom tool
- Namespace tool
- Web search tool
Show child attributes
Show child attributes
Controls tool-calling behavior. With auto, the model decides whether to call a tool.
auto Always false.
Always false.
Always null.
Always null.
Was this page helpful?