Kimi K3

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /openai/v1/responses

Full URL: https://ai.modelfold.online/openai/v1/responses

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

WARNING

⚠️ Chat only

This model currently supports chat requests only and has not yet been adapted for agent use. Connecting it to an agent may cause request errors or unexpected results.

Kimi K3 is an OpenAI Responses–compatible endpoint that supports chat, function calling, image input, streaming, and reasoning, with a 1M-token context window.

• Reasoning — Reasoning is on by default. reasoning.effort can be low / medium / high .
• Image input — Mix text and images in a single message.
• Function calling — Custom function calling, with optional JSON-constrained answers.
• Unified endpoint — Use the unified /openai/v1/responses endpoint with model set to kimi-k3 .

Reasoning

The model reasons by default. Higher reasoning.effort means more thorough reasoning and possibly higher latency.

• low: faster
• medium: balanced
• high: more thorough, better for complex questions

If omitted, the model chooses. Reasoning summaries are for display only and do not need to be sent back as input.

WARNING

This model does not support web search. Built-in tools such as web_search are ignored.

Tools and input

Basic chat (streaming)

{
  "model": "kimi-k3",
  "stream": true,
  "input": "Introduce Beijing in one sentence"
}

Multi-turn chat + instructions (non-streaming)

{
  "model": "kimi-k3",
  "stream": false,
  "instructions": "Answer in English only",
  "input": [
    { "role": "user", "content": "My name is Xiaoming" },
    { "role": "assistant", "content": "Hi Xiaoming." },
    { "role": "user", "content": "What is my name?" }
  ]
}

Set reasoning effort

{
  "model": "kimi-k3",
  "stream": true,
  "reasoning": { "effort": "high" },
  "input": "Which is larger, 9.11 or 9.9?"
}

Function calling

Declare functions the model can call. Only function tools are supported. After you pass tools, set tool_choice to auto to let the model decide, or pass an object to pin a specific function. Do not send tool_choice if you are not sending tools.

{
  "model": "kimi-k3",
  "stream": false,
  "input": "What's the weather like in Shanghai right now?",
  "tool_choice": "auto",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "City name" }
        },
        "required": ["city"],
        "additionalProperties": false
      }
    }
  ]
}

Return function results

The model returns a function_call. After you run the function, append both that item and your function_call_output to input, paired by call_id:

{
  "model": "kimi-k3",
  "stream": false,
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "City name" }
        },
        "required": ["city"],
        "additionalProperties": false
      }
    }
  ],
  "input": [
    { "role": "user", "content": "What's the weather like in Beijing right now?" },
    {
      "type": "function_call",
      "call_id": "call_6102a526bdda4ebf8e982aa3",
      "name": "get_weather",
      "arguments": "{\"city\":\"Beijing\"}"
    },
    {
      "type": "function_call_output",
      "call_id": "call_6102a526bdda4ebf8e982aa3",
      "output": "{\"temp_c\":21,\"condition\":\"sunny\"}"
    }
  ]
}

JSON output

Set text.format to constrain the answer to JSON:

{ "text": { "format": { "type": "json_object" } } }

Use json_schema to validate the answer against your own schema.

{
  "model": "kimi-k3",
  "stream": false,
  "input": "Give information about Tokyo",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "city_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string" },
          "country": { "type": "string" }
        },
        "required": ["city", "country"],
        "additionalProperties": false
      }
    }
  }
}

Image input

Mix input_image and input_text parts in the same message. image_url can be a publicly reachable image URL or data:image/{format};base64,{data}:

{
  "model": "kimi-k3",
  "stream": false,
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "What's in this image?" },
        { "type": "input_image", "image_url": "https://example.com/cat.png" }
      ]
    }
  ]
}

Error handling

Check the response body, not only the HTTP status. Errors are returned either as {"code": ..., "msg": "..."} (for example 401 invalid API key, 402 insufficient credits, 429 rate limited; the HTTP status may still be 200) or as {"error": {"type": "...", "message": "..."}}.

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
model	string	Yes	Target model name. Allowed value: kimi-k3. Allowed values：kimi-k3。 示例：kimi-k3。
input	`string	array<object	object
instructions	string	No	System instructions for the model, inserted as a system message before input. 示例：Answer in Chinese only。
stream	boolean	No	When true, the response is streamed as server-sent events. When false, the full response is returned after completion. Defaults to true. Default：true。 示例：true。
reasoning	object	No	Reasoning settings. Reasoning is on by default.
reasoning.effort	string	No	Reasoning effort. Higher values reason more thoroughly and may add latency. Allowed: low, medium, high. If omitted, the model chooses. Allowed values：low / medium / high。 示例：low。
tools	array&lt;object&gt;	No	Optional list of tools the model can call. Only function is supported. Built-in tools such as web_search are ignored.
tools[].type	string	Yes	Tool type. Always function.
tools[].name	string	Yes	Function name. Returned as-is when the model calls it. 示例：get_weather。
tools[].description	string	No	What the function does. Helps the model decide when to call it. 示例：Get the current weather for a city。
tools[].parameters	object	Yes	Function parameter definition as a JSON Schema object.
tools[].strict	boolean	No	Whether to generate arguments strictly from parameters.
tool_choice	`string	object`	No
text	object	No	Output format settings.
text.format	`object	object	object`

Request Example

curl -X POST "https://ai.modelfold.online/openai/v1/responses" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kimi-k3",
  "stream": true,
  "input": "Introduce Beijing in one sentence"
}'

{
  "model": "kimi-k3",
  "stream": true,
  "input": "Introduce Beijing in one sentence"
}

Response

200 — Success. stream=true (default) returns text/event-stream; stream=false returns application/json. Pre-check failures also return HTTP 200 — use code to tell them apart.

Text reply (stream=false)

{
  "id": "resp_551f7700-da28-4b8d-b831-9a675b85e73a",
  "object": "response",
  "created_at": 1790128550,
  "status": "completed",
  "model": "moonshotai/kimi-k3",
  "output": [
    {
      "type": "reasoning",
      "id": "rs_b1beab9c6ba54a7598441ed82d771f89",
      "status": "completed",
      "summary": [
        {
          "type": "summary_text",
          "text": "The user wants a one-sentence introduction to Beijing…"
        }
      ]
    },
    {
      "type": "message",
      "id": "msg_347976f56b104ab291ebcc068164502c",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "text": "Beijing is China's capital, a historic city with more than three thousand years of urban history, home to landmarks such as the Forbidden City and the Great Wall, and a modern international metropolis."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 92,
    "output_tokens": 341,
    "total_tokens": 433,
    "output_tokens_details": {
      "reasoning_tokens": 291
    }
  },
  "credits_consumed": 1.08
}

Function call (stream=false)

{
  "id": "resp_4b5fff52-b406-4b34-9ca5-144960efa291",
  "object": "response",
  "created_at": 1790142133,
  "status": "completed",
  "model": "moonshotai/kimi-k3",
  "output": [
    {
      "type": "reasoning",
      "id": "rs_f7190261f68f4640bda70ff51778d3a1",
      "status": "completed",
      "summary": [
        {
          "type": "summary_text",
          "text": "The user asked about the weather in Shanghai, so call get_weather."
        }
      ]
    },
    {
      "type": "function_call",
      "id": "fc_ce486f4cebab4ae2b4b8d200ce34086a",
      "status": "completed",
      "name": "get_weather",
      "arguments": "{\"city\": \"Shanghai\"}",
      "call_id": "call_6102a526bdda4ebf8e982aa3"
    }
  ],
  "usage": {
    "input_tokens": 174,
    "output_tokens": 61,
    "total_tokens": 235,
    "output_tokens_details": {
      "reasoning_tokens": 11
    }
  },
  "credits_consumed": 0.29
}

Pre-check failed: insufficient credits

{
  "code": 402,
  "msg": "Credits insufficient : Your current balance isn’t enough to run this request. Please top up to continue.",
  "data": null
}

Pre-check failed: invalid API key

{
  "code": 401,
  "msg": "The api key does not exist.",
  "data": null
}

Pre-check failed: too many requests

{
  "code": 429,
  "msg": "Your call frequency is too high. Please try again later.",
  "data": null
}

Cannot download image

{
  "error": {
    "type": "server_error",
    "message": "Cannot download image [image-url] ...",
    "param": null,
    "code": null
  }
}

Generation failed

{
  "error": {
    "type": "server_error",
    "message": "Server exception, please try again later",
    "param": null,
    "code": null
  }
}

Service under maintenance

{
  "error": {
    "type": "server_error",
    "message": "The server is currently being maintained, please try again later~",
    "param": null,
    "code": null
  }
}

400 — The model rejected the request, for example because an image URL could not be downloaded.

参数	类型	必填	说明
error	object	否	Error details.
error.type	string	否	Error type. 示例：server_error。
error.message	string	否	Error message.
error.param	string	否	The parameter that failed. Usually null.
error.code	string	否	Error code. Usually null.

{
  "error": {
    "type": "server_error",
    "message": "A serene mountain landscape at sunrise",
    "param": "",
    "code": ""
  }
}

429 — Service is at capacity. Try again later.

参数	类型	必填	说明
error	object	否	Error details.
error.type	string	否	Error type. 示例：server_error。
error.message	string	否	Error message.
error.param	string	否	The parameter that failed. Usually null.
error.code	string	否	Error code. Usually null.

{
  "error": {
    "type": "server_error",
    "message": "A serene mountain landscape at sunrise",
    "param": "",
    "code": ""
  }
}

500 — Generation failed.

参数	类型	必填	说明
error	object	否	Error details.
error.type	string	否	Error type. 示例：server_error。
error.message	string	否	Error message.
error.param	string	否	The parameter that failed. Usually null.
error.code	string	否	Error code. Usually null.

{
  "error": {
    "type": "server_error",
    "message": "A serene mountain landscape at sunrise",
    "param": "",
    "code": ""
  }
}

502 — Service is temporarily unavailable. Try again later.

参数	类型	必填	说明
error	object	否	Error details.
error.type	string	否	Error type. 示例：server_error。
error.message	string	否	Error message.
error.param	string	否	The parameter that failed. Usually null.
error.code	string	否	Error code. Usually null.

{
  "error": {
    "type": "server_error",
    "message": "A serene mountain landscape at sunrise",
    "param": "",
    "code": ""
  }
}