{ "openapi": "3.1.0", "info": { "title": "Moonshot AI API", "version": "1.0.0", "description": "API for Moonshot AI / Kimi large language model services" }, "servers": [ { "url": "https://api.moonshot.ai", "description": "Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "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](https://platform.kimi.ai/console/api-keys) in your dashboard." } }, "schemas": { "Message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ], "example": "user", "description": "The role of the message sender. Supports system, user, assistant, tool." }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "oneOf": [ { "title": "text", "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "title": "image_url", "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, { "type": "string" } ] } }, "required": [ "type", "image_url" ] }, { "title": "video_url", "type": "object", "properties": { "type": { "type": "string", "enum": [ "video_url" ] }, "video_url": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, { "type": "string" } ] } }, "required": [ "type", "video_url" ] } ] } } ], "example": "Hello", "description": "The content of the message. Can be a plain text string, or an array of objects with text/image_url/video_url types (for multimodal input)" }, "name": { "type": "string", "default": null, "description": "Optional name for the message sender" }, "partial": { "type": "boolean", "default": false, "description": "Enable Partial Mode by setting this to true in the last assistant message" } }, "required": [ "role", "content" ] }, "ToolDefinition": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string", "description": "Function name. Must follow the regex: ^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$", "pattern": "^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$" }, "description": { "type": "string", "description": "Description of what the function does" }, "parameters": { "type": "object", "description": "Function parameters as JSON Schema. Must conform to the [MFJS (Moonshot Flavored JSON Schema) specification](https://github.com/MoonshotAI/walle/blob/main/docs/mfjs-spec.md).", "additionalProperties": true }, "strict": { "type": "boolean", "default": true, "description": "Whether to strictly constrain tool call arguments according to the parameters schema. Defaults to true. When false, only guarantees the output is a valid JSON object without enforcing internal structure." } }, "required": [ "name", "parameters" ] } }, "required": [ "type", "function" ] }, "KimiK3DynamicToolMessage": { "type": "object", "description": "A Kimi K3 dynamic tool loading message. This message must use the system role, declares tools available to subsequent conversation turns from its position, and does not include a content field.", "properties": { "role": { "type": "string", "enum": [ "system" ], "description": "The role of a dynamic tool loading message. Always system." }, "tools": { "type": "array", "description": "Tools available for the model to call from this message onward", "items": { "$ref": "#/components/schemas/ToolDefinition" } } }, "required": [ "role", "tools" ], "additionalProperties": false }, "KimiK3Message": { "oneOf": [ { "title": "Standard message", "$ref": "#/components/schemas/Message" }, { "title": "Dynamic tool message", "$ref": "#/components/schemas/KimiK3DynamicToolMessage" } ], "description": "A Kimi K3 conversation message. Supports both standard messages and system messages that omit content and declare dynamically loaded tools through tools." }, "ChatRequestCommon": { "type": "object", "properties": { "logprobs": { "type": "boolean", "default": false, "description": "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." }, "top_logprobs": { "type": "integer", "minimum": 0, "maximum": 20, "description": "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." }, "prediction": { "type": "object", "description": "Configuration 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).", "properties": { "type": { "type": "string", "enum": [ "content" ], "description": "The type of the predicted content. Currently only content is supported." }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ], "description": "The static predicted output content that should be matched when generating the model response, such as the content of a text file being regenerated. Accepts a string or an array of content parts (text parts only)." } } }, "max_tokens": { "type": "integer", "deprecated": true, "description": "Deprecated, please refer to max_completion_tokens" }, "max_completion_tokens": { "type": "integer", "description": "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": { "type": "object", "description": "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).", "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ], "description": "Output format type. text: default, plain text output; json_object: ensures output is a valid JSON object; json_schema: constrains output to match a specified JSON Schema (recommended, requires the json_schema field)" }, "json_schema": { "type": "object", "description": "Used when type is json_schema. Defines the JSON Schema that the output should conform to.", "properties": { "name": { "type": "string", "description": "Schema name for identification" }, "strict": { "type": "boolean", "default": true, "description": "Whether to strictly constrain output according to the schema. Defaults to true. When true, the schema must conform to the MFJS specification; non-conforming schemas will return errors or warnings. When false, only guarantees the output is a valid JSON object without enforcing internal structure." }, "schema": { "type": "object", "description": "The JSON Schema object defining the structure the output should conform to. Must conform to MFJS (Moonshot Flavored JSON Schema) specification. You can use the walle CLI tool to validate: go install github.com/moonshotai/walle/cmd/walle@latest && walle -schema 'your_schema' -level strict", "additionalProperties": true } }, "required": [ "name", "schema" ] } } }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 5 } ], "default": null, "description": "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": { "type": "boolean", "default": false, "description": "Whether to return the response in a streaming fashion. Default is false." }, "stream_options": { "type": "object", "description": "Options for streaming responses", "properties": { "include_usage": { "type": "boolean", "default": false, "description": "If set, an additional chunk will be streamed before the data: [DONE] message. The usage field on this chunk shows the token usage statistics for the entire request, and the choices field will always be an empty array. All other chunks will also include a usage field, but with a null value. NOTE: If the stream is interrupted, you may not receive the final usage chunk which contains the total token usage for the request" } } }, "tools": { "type": "array", "description": "A list of tools the model may call", "items": { "$ref": "#/components/schemas/ToolDefinition" } }, "prompt_cache_key": { "type": "string", "default": null, "description": "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" }, "prompt_cache_options": { "type": "object", "description": "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", "properties": { "mode": { "type": "string", "enum": [ "implicit" ], "default": "implicit", "description": "Cache write mode. Only implicit is supported: automatically writes the request prefix to the cache" }, "ttl": { "type": "string", "enum": [ "5m", "1h" ], "default": "5m", "description": "Lifetime of the written cache. The 5m and 1h tiers are independent of each other. When a request with the same prefix hits the cache within its lifetime, the cache entry is refreshed with its original TTL" } } }, "safety_identifier": { "type": "string", "description": "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": { "oneOf": [ { "type": "string", "enum": [ "auto", "none", "required" ], "description": "auto: the model decides whether to call tools; none: no tool calls; required: force a tool call" }, { "type": "object", "description": "Force a specific tool call", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function to call" } }, "required": [ "name" ] } }, "required": [ "type", "function" ] } ], "description": "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." } } }, "ChatRequestBase": { "type": "object", "properties": { "logprobs": { "type": "boolean", "default": false, "description": "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." }, "top_logprobs": { "type": "integer", "minimum": 0, "maximum": 20, "description": "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." }, "prediction": { "type": "object", "description": "Configuration 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).", "properties": { "type": { "type": "string", "enum": [ "content" ], "description": "The type of the predicted content. Currently only content is supported." }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ], "description": "The static predicted output content that should be matched when generating the model response, such as the content of a text file being regenerated. Accepts a string or an array of content parts (text parts only)." } } }, "messages": { "type": "array", "description": "A list of messages in the conversation so far. Each element has the format {\"role\": \"user\", \"content\": \"Hello\"}. role supports system, user, assistant, or tool. content must not be empty. The content field can be a string or an array[object] (for multimodal input).", "items": { "$ref": "#/components/schemas/Message" } }, "max_tokens": { "type": "integer", "deprecated": true, "description": "Deprecated, please refer to max_completion_tokens" }, "max_completion_tokens": { "type": "integer", "description": "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": { "type": "object", "description": "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).", "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ], "description": "Output format type. text: default, plain text output; json_object: ensures output is a valid JSON object; json_schema: constrains output to match a specified JSON Schema (recommended, requires the json_schema field)" }, "json_schema": { "type": "object", "description": "Used when type is json_schema. Defines the JSON Schema that the output should conform to.", "properties": { "name": { "type": "string", "description": "Schema name for identification" }, "strict": { "type": "boolean", "default": true, "description": "Whether to strictly constrain output according to the schema. Defaults to true. When true, the schema must conform to the MFJS specification; non-conforming schemas will return errors or warnings. When false, only guarantees the output is a valid JSON object without enforcing internal structure." }, "schema": { "type": "object", "description": "The JSON Schema object defining the structure the output should conform to. Must conform to MFJS (Moonshot Flavored JSON Schema) specification. You can use the walle CLI tool to validate: go install github.com/moonshotai/walle/cmd/walle@latest && walle -schema 'your_schema' -level strict", "additionalProperties": true } }, "required": [ "name", "schema" ] } } }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 5 } ], "default": null, "description": "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": { "type": "boolean", "default": false, "description": "Whether to return the response in a streaming fashion. Default is false." }, "stream_options": { "type": "object", "description": "Options for streaming responses", "properties": { "include_usage": { "type": "boolean", "default": false, "description": "If set, an additional chunk will be streamed before the data: [DONE] message. The usage field on this chunk shows the token usage statistics for the entire request, and the choices field will always be an empty array. All other chunks will also include a usage field, but with a null value. NOTE: If the stream is interrupted, you may not receive the final usage chunk which contains the total token usage for the request" } } }, "tools": { "type": "array", "description": "A list of tools the model may call", "items": { "$ref": "#/components/schemas/ToolDefinition" } }, "prompt_cache_key": { "type": "string", "default": null, "description": "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" }, "prompt_cache_options": { "type": "object", "description": "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", "properties": { "mode": { "type": "string", "enum": [ "implicit" ], "default": "implicit", "description": "Cache write mode. Only implicit is supported: automatically writes the request prefix to the cache" }, "ttl": { "type": "string", "enum": [ "5m", "1h" ], "default": "5m", "description": "Lifetime of the written cache. The 5m and 1h tiers are independent of each other. When a request with the same prefix hits the cache within its lifetime, the cache entry is refreshed with its original TTL" } } }, "safety_identifier": { "type": "string", "description": "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": { "oneOf": [ { "type": "string", "enum": [ "auto", "none", "required" ], "description": "auto: the model decides whether to call tools; none: no tool calls; required: force a tool call" }, { "type": "object", "description": "Force a specific tool call", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function to call" } }, "required": [ "name" ] } }, "required": [ "type", "function" ] } ], "description": "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." } }, "required": [ "messages" ] }, "KimiK3ChatRequest": { "title": "kimi-k3", "allOf": [ { "$ref": "#/components/schemas/ChatRequestCommon" }, { "type": "object", "properties": { "model": { "type": "string", "description": "Model ID", "enum": [ "kimi-k3" ], "default": "kimi-k3" }, "messages": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/KimiK3Message" } }, "reasoning_effort": { "type": "string", "enum": [ "low", "high", "max" ], "default": "max", "description": "Kimi K3 always enables thinking with Preserved Thinking. Reasoning effort supports low, high, and max, with max as the default." } }, "required": [ "model", "messages" ] } ] }, "KimiK26ChatRequest": { "title": "kimi-k2.6", "allOf": [ { "$ref": "#/components/schemas/ChatRequestBase" }, { "type": "object", "properties": { "model": { "type": "string", "description": "Model ID", "enum": [ "kimi-k2.6" ], "default": "kimi-k2.6" }, "thinking": { "type": "object", "description": "Controls whether thinking is enabled for the kimi-k2.6 model, and whether to fully preserve reasoning_content across multi-turn conversations. Optional parameter. Default value is {\"type\": \"enabled\"}.", "properties": { "type": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Enable or disable thinking capability" }, "keep": { "type": [ "string", "null" ], "enum": [ "all", null ], "description": "Controls whether reasoning_content from previous turns is preserved across a multi-turn conversation, i.e. whether to enable Preserved Thinking. Defaults to `null`, meaning historical thinking is NOT preserved.\n\n- `null` (default) or omitted: The server ignores reasoning_content from historical turns.\n- `\"all\"`: Preserves reasoning_content from historical turns and provides it to the model as part of the context, enabling Preserved Thinking. When using this, keep the reasoning_content from every historical assistant message in messages as-is. Recommended to use together with `type: \"enabled\"`.\n- Note: This parameter only affects reasoning_content from historical turns; it does not change whether the model produces/outputs thinking within the current turn (that is controlled by `type`). For best practices, see [Preserved Thinking](/guide/use-thinking-models#preserved-thinking)." } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "model" ] } ] }, "KimiK27CodeChatRequest": { "title": "kimi-k2.7-code", "allOf": [ { "$ref": "#/components/schemas/ChatRequestBase" }, { "type": "object", "properties": { "model": { "type": "string", "description": "Model ID. Either `kimi-k2.7-code` or its high-speed variant `kimi-k2.7-code-highspeed`; the two are the same model with identical parameters, while the high-speed variant outputs at approximately 180 Tokens/s (up to 260 Tokens/s in short-context scenarios).", "enum": [ "kimi-k2.7-code", "kimi-k2.7-code-highspeed" ], "default": "kimi-k2.7-code" }, "thinking": { "type": "object", "description": "Controls thinking for the kimi-k2.7-code model, and whether to fully preserve reasoning_content across multi-turn conversations. Optional parameter. Default value is {\"type\": \"enabled\", \"keep\": \"all\"}.\n\nDifferences from kimi-k2.6:\n- `type` only accepts `\"enabled\"`. Unlike kimi-k2.6, `\"disabled\"` is NOT supported — passing it returns an error. Thinking is always on for this model.\n- `keep` only accepts the valid value `\"all\"`; omitting it or passing `\"all\"` is treated as `\"all\"` on the server, while any other invalid value returns an error. Preserved Thinking is therefore always enabled for this model.", "properties": { "type": { "type": "string", "enum": [ "enabled" ], "description": "Enable thinking capability. For kimi-k2.7-code, only `\"enabled\"` is accepted; passing `\"disabled\"` returns an error. This differs from kimi-k2.6, which also supports `\"disabled\"`." }, "keep": { "type": [ "string", "null" ], "enum": [ "all", null ], "description": "Controls whether reasoning_content from previous turns is preserved across a multi-turn conversation, i.e. whether to enable Preserved Thinking.\n\n- For kimi-k2.7-code this parameter only accepts the valid value `\"all\"`: passing `\"all\"`, passing `null`, or omitting it all behave identically and are treated as `\"all\"` on the server — reasoning_content from historical turns is always preserved; passing any other invalid value returns an error. This differs from kimi-k2.6, whose default is `null` (historical thinking NOT preserved unless you explicitly set `\"all\"`).\n- Because Preserved Thinking is always on, keep the reasoning_content from every historical assistant message in messages as-is.\n- Note: This parameter only affects reasoning_content from historical turns; it does not change whether the model produces/outputs thinking within the current turn (that is controlled by `type`). For best practices, see [Preserved Thinking](/guide/use-thinking-models#preserved-thinking)." } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "model" ] } ] }, "ChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the completion" }, "object": { "type": "string", "description": "Object type", "example": "chat.completion" }, "created": { "type": "integer", "description": "Unix timestamp of when the completion was created" }, "model": { "type": "string", "description": "Model used for the completion" }, "choices": { "type": "array", "description": "List of completion choices", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": [ "string", "null" ], "description": "The assistant's message content" }, "tool_calls": { "type": "array", "description": "Tool calls made by the model", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON string of function arguments" } } } } } }, "reasoning_content": { "type": [ "string", "null" ], "description": "Reasoning process (returned only when thinking mode is enabled)" } } }, "finish_reason": { "type": "string", "enum": [ "stop", "length", "tool_calls" ] } } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "description": "Number of tokens in the prompt" }, "completion_tokens": { "type": "integer", "description": "Number of tokens in the completion" }, "total_tokens": { "type": "integer", "description": "Total number of tokens used" }, "cached_tokens": { "type": "integer", "description": "Number of tokens served from cache" }, "prompt_tokens_details": { "type": "object", "description": "Breakdown of prompt tokens. cached_tokens, cache_write_tokens and the uncached remainder are mutually exclusive and sum to prompt_tokens", "properties": { "cached_tokens": { "type": "integer", "description": "Number of tokens served from cache" }, "cache_write_tokens": { "type": "integer", "description": "Number of tokens written to the cache by this request. Billed according to the TTL at write time; see prompt_cache_options" } }, "required": [ "cached_tokens", "cache_write_tokens" ] } } } } }, "ChatCompletionChunk": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the completion" }, "object": { "type": "string", "description": "Object type", "example": "chat.completion.chunk" }, "created": { "type": "integer", "description": "Unix timestamp of when the completion was created" }, "model": { "type": "string", "description": "Model used for the completion" }, "choices": { "type": "array", "description": "List of completion choices", "items": { "$ref": "#/components/schemas/ChoiceDelta" } }, "usage": { "type": [ "object", "null" ], "description": "Token usage statistics. Object in the final chunk with usage, null in ordinary chunks", "properties": { "prompt_tokens": { "type": "integer", "description": "Number of tokens in the prompt" }, "completion_tokens": { "type": "integer", "description": "Number of tokens in the completion" }, "total_tokens": { "type": "integer", "description": "Total number of tokens used" }, "cached_tokens": { "type": "integer", "description": "Number of tokens served from cache" }, "prompt_tokens_details": { "type": "object", "description": "Breakdown of prompt tokens. cached_tokens, cache_write_tokens and the uncached remainder are mutually exclusive and sum to prompt_tokens", "properties": { "cached_tokens": { "type": "integer", "description": "Number of tokens served from cache" }, "cache_write_tokens": { "type": "integer", "description": "Number of tokens written to the cache by this request. Billed according to the TTL at write time; see prompt_cache_options" } }, "required": [ "cached_tokens", "cache_write_tokens" ] } } } } }, "ChoiceDelta": { "type": "object", "properties": { "index": { "type": "integer", "description": "Choice index" }, "delta": { "type": "object", "description": "Incremental content object", "properties": { "role": { "type": "string", "description": "Message role (only present in the first chunk)" }, "content": { "type": "string", "description": "Message content fragment" }, "tool_calls": { "type": "array", "description": "Tool calls initiated by the model", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "JSON string of function arguments" } } } } } } } }, "finish_reason": { "type": [ "string", "null" ], "enum": [ "stop", "length", "tool_calls", null ], "description": "Stop reason, only present in the final chunk" }, "usage": { "type": "object", "description": "Token usage statistics (optional)", "properties": { "prompt_tokens": { "type": "integer", "description": "Number of tokens in the prompt" }, "completion_tokens": { "type": "integer", "description": "Number of tokens in the completion" }, "total_tokens": { "type": "integer", "description": "Total number of tokens used" } } } } }, "ResponsesRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "ID of the model to use. This endpoint currently supports `kimi-k3`.", "example": "kimi-k3" }, "input": { "description": "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.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ResponsesInputItem" } } ] }, "instructions": { "type": "string", "description": "Top-level system instructions, applied ahead of every input item." }, "stream": { "type": "boolean", "default": false, "description": "When true, the response is delivered as a stream of SSE events." }, "max_output_tokens": { "type": "integer", "description": "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": { "type": "object", "description": "Reasoning configuration.", "properties": { "effort": { "type": "string", "enum": [ "low", "high", "max" ], "default": "max", "description": "Reasoning depth. Higher levels reason more thoroughly, which usually also increases latency and reasoning token usage." } } }, "text": { "type": "object", "description": "Output text configuration.", "properties": { "format": { "type": "object", "required": [ "type", "schema" ], "description": "Constrains the output structure with a JSON Schema.", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "name": { "type": "string", "description": "Schema name. Defaults to `output`." }, "schema": { "type": "object", "description": "JSON Schema describing the output structure." }, "strict": { "type": "boolean", "description": "Whether the output must strictly conform to the schema." } } } } }, "tools": { "type": "array", "description": "List of tools the model may call.", "items": { "$ref": "#/components/schemas/ResponsesTool" } }, "tool_choice": { "$ref": "#/components/schemas/ResponsesToolChoice" }, "include": { "type": "array", "items": { "type": "string", "enum": [ "web_search_call.results", "web_search_call.action.sources" ] }, "description": "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." }, "prompt_cache_key": { "type": "string", "description": "Context cache identifier. Reusing the same value across a session improves cache hit rate." }, "prompt_cache_options": { "type": "object", "description": "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", "properties": { "mode": { "type": "string", "enum": [ "implicit" ], "default": "implicit", "description": "Cache write mode. Only implicit is supported: automatically writes the request prefix to the cache" }, "ttl": { "type": "string", "enum": [ "5m", "1h" ], "default": "5m", "description": "Lifetime of the written cache. The 5m and 1h tiers are independent of each other. When a request with the same prefix hits the cache within its lifetime, the cache entry is refreshed with its original TTL" } } }, "safety_identifier": { "type": "string", "description": "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" } } }, "ResponsesInputItem": { "description": "An element of the input array, discriminated by `type`. When `type` is omitted the item is treated as `message`.", "oneOf": [ { "$ref": "#/components/schemas/ResponsesMessageItem" }, { "$ref": "#/components/schemas/ResponsesReasoningItem" }, { "$ref": "#/components/schemas/ResponsesFunctionCallItem" }, { "$ref": "#/components/schemas/ResponsesFunctionCallOutputItem" }, { "$ref": "#/components/schemas/ResponsesCustomToolCallItem" }, { "$ref": "#/components/schemas/ResponsesCustomToolCallOutputItem" }, { "$ref": "#/components/schemas/ResponsesWebSearchCallItem" }, { "$ref": "#/components/schemas/ResponsesAdditionalToolsItem" } ] }, "ResponsesMessageItem": { "type": "object", "title": "Message", "description": "A conversation message. `type` may be omitted.", "required": [ "role", "content" ], "properties": { "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "user", "assistant", "developer" ], "description": "Message role. `developer` is handled as a system instruction." }, "content": { "description": "Message content, either a string or an array of content parts.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ResponsesInputContentPart" } } ] }, "status": { "type": "string", "enum": [ "completed" ] } } }, "ResponsesReasoningItem": { "type": "object", "title": "Reasoning", "description": "Replays reasoning content from a previous turn. `content` takes precedence over `summary`.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "reasoning" ] }, "id": { "type": "string" }, "summary": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "content": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "reasoning_text" ] }, "text": { "type": "string" } } } }, "status": { "type": "string", "enum": [ "completed" ] } } }, "ResponsesFunctionCallItem": { "type": "object", "title": "Function call", "description": "Replays a function call.", "required": [ "type", "call_id", "name", "arguments" ], "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string", "description": "Call ID paired with the matching `function_call_output`." }, "name": { "type": "string" }, "namespace": { "type": "string", "description": "Namespace the tool belongs to, returned for namespace tool calls." }, "arguments": { "type": "string", "description": "JSON string of the function arguments." }, "status": { "type": "string", "enum": [ "completed" ] } } }, "ResponsesFunctionCallOutputItem": { "type": "object", "title": "Function call output", "description": "Result of executing a function call.", "required": [ "type", "call_id", "output" ], "properties": { "type": { "type": "string", "enum": [ "function_call_output" ] }, "call_id": { "type": "string", "description": "Same call ID as the matching `function_call`." }, "output": { "description": "Content returned by the tool.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ResponsesInputContentPart" } } ] }, "status": { "type": "string", "enum": [ "completed" ] } } }, "ResponsesCustomToolCallItem": { "type": "object", "title": "Custom tool call", "description": "Replays a custom tool call.", "required": [ "type", "call_id", "name", "input" ], "properties": { "type": { "type": "string", "enum": [ "custom_tool_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string", "description": "Call ID paired with the matching `custom_tool_call_output`." }, "name": { "type": "string" }, "namespace": { "type": "string", "description": "Namespace the tool belongs to, returned for namespace tool calls." }, "input": { "type": "string", "description": "Free-form text input generated by the model." }, "status": { "type": "string", "enum": [ "completed" ] } } }, "ResponsesCustomToolCallOutputItem": { "type": "object", "title": "Custom tool call output", "description": "Result of executing a custom tool call.", "required": [ "type", "call_id", "output" ], "properties": { "type": { "type": "string", "enum": [ "custom_tool_call_output" ] }, "call_id": { "type": "string", "description": "Same call ID as the matching `custom_tool_call`." }, "output": { "description": "Content returned by the tool.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ResponsesInputContentPart" } } ] }, "status": { "type": "string", "enum": [ "completed" ] } } }, "ResponsesWebSearchCallItem": { "type": "object", "title": "Web search call", "description": "Replays a previous web search call. Kept for history only and ignored during conversion; the search results are already carried by the assistant message that follows.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search_call" ] }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "completed" ] }, "action": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search" ] }, "query": { "type": "string" } } } } }, "ResponsesAdditionalToolsItem": { "type": "object", "title": "Additional tools", "description": "Adds callable tools partway through a conversation, effective from the position of this item.", "required": [ "type", "role", "tools" ], "properties": { "type": { "type": "string", "enum": [ "additional_tools" ] }, "id": { "type": "string" }, "role": { "type": "string", "enum": [ "developer" ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ResponsesTool" } } } }, "ResponsesInputContentPart": { "description": "An element of a content array, discriminated by `type`.", "oneOf": [ { "type": "object", "title": "Input text", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "input_text" ] }, "text": { "type": "string" } } }, { "type": "object", "title": "Input image", "required": [ "type", "image_url" ], "properties": { "type": { "type": "string", "enum": [ "input_image" ] }, "image_url": { "type": "string", "description": "Data URL of the image, for example `data:image/png;base64,`. Public http(s) URLs are not supported." }, "detail": { "type": "string", "enum": [ "auto", "low", "high", "original" ] } } }, { "type": "object", "title": "Output text", "description": "Used when replaying assistant text from history.", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } } } ] }, "ResponsesTool": { "description": "A tool definition, discriminated by `type`. Supported types are `function`, `custom` (only `apply_patch`), `namespace`, and `web_search`; other tool types are not supported.", "oneOf": [ { "$ref": "#/components/schemas/ResponsesFunctionTool" }, { "$ref": "#/components/schemas/ResponsesCustomTool" }, { "$ref": "#/components/schemas/ResponsesNamespaceTool" }, { "$ref": "#/components/schemas/ResponsesWebSearchTool" } ], "discriminator": { "propertyName": "type", "mapping": { "function": "#/components/schemas/ResponsesFunctionTool", "custom": "#/components/schemas/ResponsesCustomTool", "namespace": "#/components/schemas/ResponsesNamespaceTool", "web_search": "#/components/schemas/ResponsesWebSearchTool" } } }, "ResponsesFunctionTool": { "type": "object", "title": "Function tool", "description": "A function tool whose arguments are described by a JSON Schema.", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string", "description": "Function name. Must follow the regex: ^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$", "pattern": "^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$" }, "description": { "type": "string" }, "parameters": { "type": "object", "description": "JSON Schema describing the function arguments." }, "strict": { "type": "boolean" } } }, "ResponsesCustomTool": { "type": "object", "title": "Custom tool", "description": "A custom tool that takes free-form text input. Only the custom tool named `apply_patch` is supported, and it must define a `grammar` + `lark` format; when the model calls it, a `custom_tool_call` item is returned in the output.", "required": [ "type", "name", "format" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "enum": [ "apply_patch" ], "description": "Tool name. Only `apply_patch` is supported." }, "description": { "type": "string" }, "format": { "type": "object", "description": "Input format constraint. Only the `grammar` type with `lark` syntax is supported.", "required": [ "type", "syntax", "definition" ], "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "syntax": { "type": "string", "enum": [ "lark" ] }, "definition": { "type": "string", "description": "The Lark grammar definition." } } } } }, "ResponsesNamespaceTool": { "type": "object", "title": "Namespace tool", "description": "Groups a set of function or custom tools under one namespace.", "required": [ "type", "name", "description", "tools" ], "properties": { "type": { "type": "string", "enum": [ "namespace" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "tools": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ResponsesFunctionTool" }, { "$ref": "#/components/schemas/ResponsesCustomTool" } ] } } } }, "ResponsesWebSearchTool": { "type": "object", "title": "Web search tool", "description": "A web search tool executed on the server side. When present, the server first decides from the input whether a search is needed; if so, it runs the search, injects the results into the model context, and returns a `web_search_call` item in the output. At most one `web_search` tool is allowed per request. `search_context_size`, `blocked_domains`, and `filters.blocked_domains` are not supported and return `invalid_request_error`; `user_location`, `external_web_access`, and `indexed_web_access` are ignored.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search" ] }, "filters": { "type": "object", "description": "Search scope filters.", "properties": { "allowed_domains": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Restrict the search to these domains, up to 100." } } }, "search_content_types": { "type": "array", "items": { "type": "string", "enum": [ "text", "image" ] }, "default": [ "text" ], "description": "Result types to search for. Defaults to `text` only. Including `image` additionally runs an image search." }, "image_settings": { "type": "object", "description": "Image search settings. Only effective when `search_content_types` includes `image`.", "properties": { "max_results": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of images to return." }, "caption": { "type": "boolean", "default": false, "description": "Whether to generate a caption for each image." } } } } }, "ResponsesToolChoice": { "type": "string", "enum": [ "auto" ], "description": "Controls tool-calling behavior. With `auto`, the model decides whether to call a tool." }, "ResponsesResponse": { "type": "object", "description": "A single model response.", "properties": { "id": { "type": "string", "description": "Unique identifier of the response.", "example": "resp_68f0c1c2d3e4f5a6b7c8d9e0" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "integer", "description": "Unix timestamp of when the response was created." }, "completed_at": { "type": [ "integer", "null" ], "description": "Unix timestamp of when the response finished. Present when `status` is `completed` or `incomplete`; `null` when `status` is `in_progress` or `failed`." }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "failed" ], "description": "Response status. The opening snapshot of a stream is `in_progress`." }, "model": { "type": "string", "description": "Model that produced the response." }, "output": { "type": "array", "description": "The output item array, ordered as web_search_call (if any), reasoning, message, tool calls.", "items": { "$ref": "#/components/schemas/ResponsesOutputItem" } }, "usage": { "oneOf": [ { "$ref": "#/components/schemas/ResponsesUsage" }, { "type": "null" } ] }, "incomplete_details": { "type": [ "object", "null" ], "description": "Reason the response is `incomplete`.", "properties": { "reason": { "type": "string", "enum": [ "max_output_tokens", "content_filter" ] } } }, "error": { "type": [ "object", "null" ], "description": "Error information when `status` is `failed`.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "instructions": { "type": [ "string", "null" ] }, "reasoning": { "type": [ "object", "null" ] }, "text": { "type": [ "object", "null" ] }, "tools": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ResponsesTool" } }, "tool_choice": { "oneOf": [ { "$ref": "#/components/schemas/ResponsesToolChoice" }, { "type": "null" } ] }, "max_output_tokens": { "type": [ "integer", "null" ] }, "temperature": { "type": [ "number", "null" ] }, "top_p": { "type": [ "number", "null" ] }, "metadata": { "type": [ "object", "null" ] }, "parallel_tool_calls": { "type": "boolean" }, "service_tier": { "type": [ "string", "null" ] }, "store": { "type": "boolean", "description": "Always `false`." }, "background": { "type": [ "boolean", "null" ], "description": "Always `false`." }, "previous_response_id": { "type": [ "string", "null" ], "description": "Always `null`." }, "conversation": { "type": [ "object", "null" ], "description": "Always `null`." }, "prompt_cache_options": { "type": "object", "description": "The context cache write options actually applied by the server. When the request omits prompt_cache_options, refer to the mode and ttl returned here", "properties": { "mode": { "type": "string", "enum": [ "implicit" ], "description": "The write mode actually applied" }, "ttl": { "type": "string", "enum": [ "5m", "1h" ], "description": "The cache lifetime actually applied" } } } } }, "ResponsesOutputItem": { "description": "An element of the output array, discriminated by `type`.", "oneOf": [ { "$ref": "#/components/schemas/ResponsesOutputReasoningItem" }, { "$ref": "#/components/schemas/ResponsesOutputMessageItem" }, { "$ref": "#/components/schemas/ResponsesOutputFunctionCallItem" }, { "$ref": "#/components/schemas/ResponsesOutputCustomToolCallItem" }, { "$ref": "#/components/schemas/ResponsesOutputWebSearchCallItem" } ], "discriminator": { "propertyName": "type", "mapping": { "reasoning": "#/components/schemas/ResponsesOutputReasoningItem", "message": "#/components/schemas/ResponsesOutputMessageItem", "function_call": "#/components/schemas/ResponsesOutputFunctionCallItem", "custom_tool_call": "#/components/schemas/ResponsesOutputCustomToolCallItem", "web_search_call": "#/components/schemas/ResponsesOutputWebSearchCallItem" } } }, "ResponsesOutputReasoningItem": { "type": "object", "title": "Reasoning", "description": "Reasoning content produced by the model.", "properties": { "type": { "type": "string", "enum": [ "reasoning" ] }, "id": { "type": "string", "example": "rs_68f0c1c2d3e4f5a6b7c8d9e0" }, "summary": { "type": "array", "description": "The reasoning content.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "summary_text" ] }, "text": { "type": "string" } } } }, "encrypted_content": { "type": [ "string", "null" ], "description": "Always `null`." }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] } } }, "ResponsesOutputMessageItem": { "type": "object", "title": "Message", "description": "Text reply produced by the model.", "properties": { "type": { "type": "string", "enum": [ "message" ] }, "id": { "type": "string", "example": "msg_68f0c1c2d3e4f5a6b7c8d9e0" }, "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" }, "annotations": { "type": "array", "items": {} } } } }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] } } }, "ResponsesOutputFunctionCallItem": { "type": "object", "title": "Function call", "description": "A function call initiated by the model.", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string", "example": "fc_68f0c1c2d3e4f5a6b7c8d9e0" }, "call_id": { "type": "string", "description": "Use this value in `function_call_output` when returning the result." }, "name": { "type": "string" }, "namespace": { "type": "string", "description": "Returned for namespace tool calls." }, "arguments": { "type": "string", "description": "JSON string of the function arguments." }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] } } }, "ResponsesOutputCustomToolCallItem": { "type": "object", "title": "Custom tool call", "description": "A custom tool call initiated by the model.", "properties": { "type": { "type": "string", "enum": [ "custom_tool_call" ] }, "id": { "type": "string", "example": "ctc_68f0c1c2d3e4f5a6b7c8d9e0" }, "call_id": { "type": "string", "description": "Use this value in `custom_tool_call_output` when returning the result." }, "name": { "type": "string" }, "namespace": { "type": "string", "description": "Returned for namespace tool calls." }, "input": { "type": "string", "description": "Free-form text input generated by the model." }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] } } }, "ResponsesOutputWebSearchCallItem": { "type": "object", "title": "Web search call", "description": "A web search call executed on the server side. Returned only when the request includes the `web_search` tool and the server decides a search is needed. It appears first in the output array.", "properties": { "type": { "type": "string", "enum": [ "web_search_call" ] }, "id": { "type": "string", "example": "ws_68f0c1c2d3e4f5a6b7c8d9e0" }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] }, "action": { "type": "object", "description": "The action performed by this search.", "properties": { "type": { "type": "string", "enum": [ "search" ] }, "query": { "type": "string", "description": "The search query actually used." }, "sources": { "type": "array", "description": "Web pages the search hit. Returned only when `include` contains `web_search_call.action.sources`.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" }, "title": { "type": "string" } } } } } }, "results": { "type": "array", "description": "Image search results. Returned only when `include` contains `web_search_call.results` and `search_content_types` includes `image`.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_result" ] }, "image_url": { "type": "string" }, "thumbnail_url": { "type": "string" }, "source_website_url": { "type": "string" }, "caption": { "type": "string", "description": "Image caption. Returned only when `image_settings.caption` is enabled." } } } } } }, "ResponsesUsage": { "type": "object", "description": "Token usage for this response.", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens, including cached tokens." }, "input_tokens_details": { "type": "object", "properties": { "cached_tokens": { "type": "integer", "description": "Number of tokens served from the context cache." }, "cache_write_tokens": { "type": "integer", "description": "Number of tokens written to the context cache." } } }, "output_tokens": { "type": "integer", "description": "Number of output tokens, including reasoning tokens." }, "output_tokens_details": { "type": "object", "properties": { "reasoning_tokens": { "type": "integer", "description": "Number of tokens spent on reasoning." } } }, "total_tokens": { "type": "integer", "description": "Total number of tokens." } } }, "ResponsesStreamEvent": { "type": "object", "description": "A single SSE event returned when `stream: true`. Each frame is `event: ` followed by `data: `, and the remaining fields of the event body vary by `type`.", "required": [ "type", "sequence_number" ], "properties": { "type": { "type": "string", "enum": [ "response.created", "response.in_progress", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.reasoning_summary_part.added", "response.reasoning_summary_part.done", "response.reasoning_summary_text.delta", "response.reasoning_summary_text.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.completed", "response.incomplete", "response.failed", "error" ] }, "sequence_number": { "type": "integer", "description": "Event sequence number, increasing monotonically from 0." } } }, "BalanceResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response code. 0 indicates success." }, "data": { "type": "object", "properties": { "available_balance": { "type": "number", "format": "float", "description": "The available balance (unit: USD), including cash balance and voucher balance. When it is less than or equal to 0, the user cannot call the inference API", "example": 49.58894 }, "voucher_balance": { "type": "number", "format": "float", "description": "The voucher balance (unit: USD), which cannot be negative", "example": 46.58893 }, "cash_balance": { "type": "number", "format": "float", "description": "The cash balance (unit: USD), which can be negative, indicating that the user owes money. When it is negative, available_balance is equal to the value of voucher_balance", "example": 3.00001 } }, "required": [ "available_balance", "voucher_balance", "cash_balance" ] }, "scode": { "type": "string", "description": "Status code", "example": "0x0" }, "status": { "type": "boolean", "description": "Request status", "example": true } }, "required": [ "code", "data", "scode", "status" ] }, "EstimateTokenRequest": { "type": "object", "properties": { "model": { "type": "string", "description": "Model ID", "default": "kimi-k3", "enum": [ "kimi-k3", "kimi-k2.7-code", "kimi-k2.7-code-highspeed", "kimi-k2.6" ] }, "messages": { "type": "array", "description": "A list of messages in the conversation so far. Each element has the format {\"role\": \"user\", \"content\": \"Hello\"}. role supports system, user, assistant, or tool. content must not be empty", "items": { "$ref": "#/components/schemas/Message" } } }, "required": [ "model", "messages" ] }, "EstimateTokenResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total_tokens": { "type": "integer", "description": "Estimated total number of tokens", "example": 80 } }, "required": [ "total_tokens" ] } }, "required": [ "data" ] }, "SignatureVerifyRequest": { "type": "object", "properties": { "nonce": { "type": "string", "description": "The nonce sent in the `X-Msh-Request-Nonce` request header of the model call, exactly as sent.", "minLength": 1, "example": "7d929748-0ae6-41c2-ab5d-a186498ad721" }, "timestamp": { "type": "integer", "format": "int64", "description": "The Unix millisecond timestamp returned in the `Msh-Request-Timestamp` response header of the model call.", "minimum": 1, "example": 1786338000123 }, "model": { "type": "string", "description": "The `model` value from the request body of the model call, exactly as sent.", "minLength": 1, "example": "kimi-k2.7-code" }, "signature": { "type": "string", "description": "The signature token returned in the `Msh-Request-Signature` response header of the model call.", "minLength": 1, "example": "reqsigv1_" } }, "required": [ "nonce", "timestamp", "model", "signature" ] }, "SignatureVerifyResponse": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the signature is valid. `true` means the signature was issued by the Kimi API and matches the submitted nonce, timestamp, and model exactly; otherwise `false`.", "example": true } }, "required": [ "valid" ] }, "FileObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique file identifier" }, "object": { "type": "string", "description": "Object type", "example": "file" }, "bytes": { "type": "integer", "description": "File size in bytes" }, "created_at": { "type": "integer", "description": "Unix timestamp when the file was created" }, "filename": { "type": "string", "description": "Original file name" }, "purpose": { "type": "string", "description": "Purpose used when uploading the file. file-extract: extract content from text-based files (such as pdf, doc, txt); images are not supported; image: upload images for vision understanding; video: upload videos for video understanding; batch: upload JSONL files for batch processing", "enum": [ "file-extract", "image", "video", "batch" ] }, "status": { "type": "string", "description": "Processing status of the file", "example": "ready" }, "status_details": { "type": "string", "description": "Additional status details when processing fails or returns warnings" } }, "required": [ "id", "object", "bytes", "created_at", "filename", "purpose", "status" ] }, "FileListResponse": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FileObject" } } }, "required": [ "object", "data" ] }, "FileDeleteResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Deleted file identifier" }, "object": { "type": "string", "example": "file" }, "deleted": { "type": "boolean", "description": "Whether the file was deleted successfully" } }, "required": [ "id", "object", "deleted" ] }, "BatchCreateRequest": { "type": "object", "properties": { "input_file_id": { "type": "string", "description": "ID of the input file, must be a .jsonl file uploaded with purpose=\"batch\"" }, "endpoint": { "type": "string", "description": "Request endpoint, currently only /v1/chat/completions is supported", "enum": [ "/v1/chat/completions" ] }, "completion_window": { "type": "string", "description": "Time window for task processing, supports formats like 12h, 1d, 3d, minimum 12h, maximum 7d" }, "metadata": { "type": "object", "description": "Custom metadata, up to 16 key-value pairs, key max 64 chars, value max 512 chars", "additionalProperties": { "type": "string", "maxLength": 512 } } }, "required": [ "input_file_id", "endpoint", "completion_window" ] }, "BatchRequestCounts": { "type": "object", "properties": { "completed": { "type": "integer", "description": "Number of completed requests" }, "failed": { "type": "integer", "description": "Number of failed requests" }, "total": { "type": "integer", "description": "Total number of requests" } }, "required": [ "completed", "failed", "total" ] }, "BatchObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the batch task" }, "object": { "type": "string", "description": "Object type, always batch", "example": "batch" }, "endpoint": { "type": "string", "description": "Request endpoint" }, "input_file_id": { "type": "string", "description": "Input file ID" }, "completion_window": { "type": "string", "description": "Processing time window" }, "status": { "type": "string", "description": "Current status: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled", "enum": [ "validating", "failed", "in_progress", "finalizing", "completed", "expired", "cancelling", "cancelled" ] }, "output_file_id": { "type": [ "string", "null" ], "description": "Output file ID for successful results" }, "error_file_id": { "type": [ "string", "null" ], "description": "Error file ID for failed results" }, "created_at": { "type": "integer", "description": "Creation timestamp (Unix)" }, "in_progress_at": { "type": [ "integer", "null" ], "description": "Execution start timestamp (Unix)" }, "expires_at": { "type": [ "integer", "null" ], "description": "Expiration timestamp (Unix)" }, "finalizing_at": { "type": [ "integer", "null" ], "description": "Result preparation start timestamp (Unix)" }, "completed_at": { "type": [ "integer", "null" ], "description": "Completion timestamp (Unix)" }, "failed_at": { "type": [ "integer", "null" ], "description": "Validation failure timestamp (Unix)" }, "cancelling_at": { "type": [ "integer", "null" ], "description": "Cancellation request timestamp (Unix)" }, "cancelled_at": { "type": [ "integer", "null" ], "description": "Cancellation completion timestamp (Unix)" }, "request_counts": { "$ref": "#/components/schemas/BatchRequestCounts" }, "metadata": { "type": [ "object", "null" ], "description": "Custom metadata", "additionalProperties": { "type": "string" } } }, "required": [ "id", "object", "endpoint", "input_file_id", "completion_window", "status", "created_at", "request_counts" ] }, "BatchListResponse": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchObject" } }, "has_more": { "type": "boolean", "description": "Whether there are more results" } }, "required": [ "object", "data" ] }, "ToolsSearchRequest": { "type": "object", "properties": { "text_query": { "type": "string", "description": "Search query text. Must not be empty." }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 60, "description": "Search timeout in seconds, from 1 to 60. If omitted, no per-request timeout is applied." }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5, "description": "Maximum number of results to return, from 1 to 20. Defaults to 5." }, "include_content": { "type": "boolean", "default": false, "description": "Whether to return full page content in each result's `text` field. Defaults to false." } }, "required": [ "text_query" ] }, "ToolsSearchResponse": { "type": "object", "properties": { "search_results": { "type": "array", "items": { "$ref": "#/components/schemas/ToolsSearchResult" }, "description": "List of search results; an empty array when nothing matches." } }, "required": [ "search_results" ] }, "ToolsSearchResult": { "type": "object", "properties": { "authority": { "type": "string", "description": "Authority level of the source." }, "date": { "type": "string", "description": "Date of the search result." }, "icon": { "type": "string", "description": "Site icon URL." }, "mime": { "type": "string", "description": "MIME type of the content." }, "site_name": { "type": "string", "description": "Site name." }, "snippet": { "type": "string", "description": "Snippet of the search result." }, "text": { "type": "string", "description": "Full page content; returned when include_content=true, otherwise an empty string." }, "title": { "type": "string", "description": "Title of the search result." }, "url": { "type": "string", "description": "URL of the search result." } }, "required": [ "authority", "date", "icon", "mime", "site_name", "snippet", "text", "title", "url" ] }, "ToolsSearchProRequest": { "type": "object", "properties": { "text_query": { "type": "string", "description": "Search query text. Must not be empty." }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 60, "description": "Search timeout in seconds, from 1 to 60. If omitted, no per-request timeout is applied." }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5, "description": "Maximum number of results to return, from 1 to 20. Defaults to 5." }, "sites": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "Restrict results to the given sites. Multiple sites are OR'd, up to 5 entries; each entry must be non-empty and must not contain whitespace or parentheses." }, "time_window": { "$ref": "#/components/schemas/ToolsSearchTimeWindow" } }, "required": [ "text_query" ] }, "ToolsSearchTimeWindow": { "type": "object", "description": "Time-window constraint on result dates. start and end are each normalized to the first day of their period before comparison; start must not be later than end.", "properties": { "start": { "type": "string", "description": "Lower bound of the time window, in YYYY / YYYY-MM / YYYY-MM-DD format." }, "end": { "type": "string", "description": "Upper bound of the time window, in YYYY / YYYY-MM / YYYY-MM-DD format." } } }, "ToolsSearchProResponse": { "type": "object", "properties": { "search_results": { "type": "array", "items": { "$ref": "#/components/schemas/ToolsSearchProResult" }, "description": "List of search results; an empty array when nothing matches." } }, "required": [ "search_results" ] }, "ToolsSearchProResult": { "type": "object", "properties": { "authority": { "type": "string", "description": "Authority level of the source." }, "date": { "type": "string", "description": "Date of the search result." }, "icon": { "type": "string", "description": "Site icon URL." }, "mime": { "type": "string", "description": "MIME type of the content." }, "site_name": { "type": "string", "description": "Site name." }, "snippet": { "type": "string", "description": "Snippet of the search result." }, "title": { "type": "string", "description": "Title of the search result." }, "url": { "type": "string", "description": "URL of the search result." }, "chunks": { "type": "array", "items": { "$ref": "#/components/schemas/ToolsSearchProChunk" }, "description": "Structured content chunks collected for each page; an empty array when no content is available." } }, "required": [ "authority", "date", "icon", "mime", "site_name", "snippet", "title", "url", "chunks" ] }, "ToolsSearchProChunk": { "type": "object", "properties": { "text": { "type": "string", "description": "Content of the chunk." }, "score": { "type": "number", "format": "float", "description": "Relevance score of the chunk to the query." } }, "required": [ "text", "score" ] }, "ToolsFetchRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the page to fetch. Only http and https are supported." } }, "required": [ "url" ] }, "ToolsFetchResponse": { "type": "object", "properties": { "url": { "type": "string", "description": "The fetched URL." }, "markdown": { "type": "string", "description": "Fetched content in Markdown. Text and images are concatenated in page order, with images rendered as `![imageN](url)` placeholders." }, "title": { "type": "string", "description": "Page title." } }, "required": [ "url", "markdown", "title" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" }, "type": { "type": "string", "description": "Error type" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message" ] } }, "required": [ "error" ] }, "MessagesTextBlockParam": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, "MessagesMessageParam": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ], "example": "user", "description": "The role of the message. Supports user and assistant. Use the top-level `system` field for the system prompt." }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "oneOf": [ { "title": "text", "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "description": "Text content" } }, "required": [ "type", "text" ] }, { "title": "image", "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "type": "object", "description": "Image source. When `type` is `base64`, provide both `media_type` and `data`; when `type` is `url`, pass an `ms://` file reference in `url`.", "properties": { "type": { "type": "string", "enum": [ "base64", "url" ] }, "media_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/gif", "image/webp" ], "description": "Image MIME type, required only when `type=base64`" }, "data": { "type": "string", "description": "Base64-encoded image content, required only when `type=base64`" }, "url": { "type": "string", "description": "Reference to an uploaded image by file ID in the form `ms://`, required only when `type=url`. See [Upload File](/api/files-upload)." } }, "required": [ "type" ] } }, "required": [ "type", "source" ] }, { "title": "thinking", "type": "object", "description": "The model's reasoning. In multi-turn conversations, pass the thinking block from the response (including `signature`) back unchanged inside the assistant message.", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string", "description": "Reasoning content" }, "signature": { "type": "string", "description": "Signature of the reasoning content; keep it unchanged when passing back" } }, "required": [ "type", "thinking" ] }, { "title": "tool_use", "type": "object", "description": "A tool call issued by the model (appears in assistant messages)", "properties": { "type": { "type": "string", "enum": [ "tool_use" ] }, "id": { "type": "string", "description": "Tool call ID; must match `tool_use_id` when submitting the result" }, "name": { "type": "string", "description": "Tool name" }, "input": { "type": "object", "description": "Tool input", "additionalProperties": true } }, "required": [ "type", "id", "name", "input" ] }, { "title": "tool_result", "type": "object", "description": "The result of a tool execution (appears in user messages)", "properties": { "type": { "type": "string", "enum": [ "tool_result" ] }, "tool_use_id": { "type": "string", "description": "The `id` of the corresponding tool_use block" }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "oneOf": [ { "title": "text", "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "description": "Text content" } }, "required": [ "type", "text" ] }, { "title": "image", "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "type": "object", "description": "Image source. When `type` is `base64`, provide both `media_type` and `data`; when `type` is `url`, pass an `ms://` file reference in `url`.", "properties": { "type": { "type": "string", "enum": [ "base64", "url" ] }, "media_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/gif", "image/webp" ], "description": "Image MIME type, required only when `type=base64`" }, "data": { "type": "string", "description": "Base64-encoded image content, required only when `type=base64`" }, "url": { "type": "string", "description": "Reference to an uploaded image by file ID in the form `ms://`, required only when `type=url`. See [Upload File](/api/files-upload)." } }, "required": [ "type" ] } }, "required": [ "type", "source" ] } ] } } ], "description": "Tool output, either a string or an array of text / image blocks" } }, "required": [ "type", "tool_use_id", "content" ] } ] } } ], "example": "Hello", "description": "Message content. Either a plain string or an array of content blocks (text / image / thinking / tool_use / tool_result)." } }, "required": [ "role", "content" ] }, "MessagesTool": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ], "description": "Tool type, may be omitted" }, "name": { "type": "string", "description": "Tool name. Must match the regular expression: ^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$", "pattern": "^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$" }, "description": { "type": "string", "description": "Description of what the tool does" }, "input_schema": { "type": "object", "description": "JSON Schema for the tool input; the top-level `type` must be `object`. Must conform to the [MFJS (Moonshot Flavored JSON Schema) specification](https://github.com/MoonshotAI/walle/blob/main/docs/mfjs-spec.md).", "additionalProperties": true } }, "required": [ "name", "input_schema" ] }, "MessagesToolChoice": { "type": "object", "description": "Controls whether the model calls tools. `auto` (default): the model decides; `any`: force a call to any tool; `none`: do not call tools.", "properties": { "type": { "type": "string", "enum": [ "auto", "any", "none" ], "default": "auto" } }, "required": [ "type" ] }, "MessagesRequest": { "title": "kimi-k3", "type": "object", "properties": { "model": { "type": "string", "description": "Model ID", "enum": [ "kimi-k3" ], "default": "kimi-k3" }, "messages": { "type": "array", "description": "The conversation messages. If the last message is from the assistant, the model continues from that content (Partial Mode).", "items": { "$ref": "#/components/schemas/MessagesMessageParam" } }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Maximum number of tokens to generate, required. If the limit is reached before the model finishes, `stop_reason` is `max_tokens`." }, "system": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/MessagesTextBlockParam" } } ], "description": "System prompt, either a string or an array of text blocks" }, "stream": { "type": "boolean", "default": false, "description": "Whether to stream the response as Server-Sent Events, default false" }, "stop_sequences": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "Stop sequences. Generation stops on an exact match; the matched sequence itself is not output. Up to 5 entries, each at most 32 bytes." }, "tools": { "type": "array", "description": "List of tools the model may call", "items": { "$ref": "#/components/schemas/MessagesTool" } }, "tool_choice": { "$ref": "#/components/schemas/MessagesToolChoice" }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string", "description": "A stable identifier for the end user or session, used to improve cache hit rate and for abuse detection. Use a hashed value; do not send personally identifiable information. For coding agents, pass the session id and keep it constant for the whole session." } } }, "cache_control": { "type": "object", "description": "Context cache write options. Only effective when passed at the top level; cache_control markers inside the messages array are ignored. When omitted, the request only attempts to read the cache (5m tier) and does not write", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ], "description": "Cache type, fixed as ephemeral" }, "ttl": { "type": "string", "enum": [ "5m", "1h" ], "default": "5m", "description": "Lifetime of the written cache. The 5m and 1h tiers are independent of each other. When a request with the same prefix hits the cache within its lifetime, the cache entry is refreshed with its original TTL" } }, "required": [ "type" ] }, "output_config": { "type": "object", "description": "Output configuration: reasoning effort and structured output", "properties": { "effort": { "type": "string", "enum": [ "low", "high", "max" ], "default": "max", "description": "Reasoning effort: low, high, or max; default max. Changing the level breaks prefix-cache hits, so decide it before the session starts." }, "format": { "type": "object", "description": "Structured output. When set, the model outputs JSON that strictly follows the given JSON Schema.", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "description": "The JSON Schema the output must follow", "additionalProperties": true } }, "required": [ "type", "schema" ] } } } }, "required": [ "model", "messages", "max_tokens" ] }, "MessagesResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the response" }, "type": { "type": "string", "enum": [ "message" ], "example": "message" }, "role": { "type": "string", "enum": [ "assistant" ] }, "model": { "type": "string", "description": "The model specified in the request" }, "content": { "type": "array", "description": "Content blocks, ordered thinking → text → tool_use", "items": { "oneOf": [ { "title": "thinking", "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking" ] }, { "title": "text", "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "title": "tool_use", "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_use" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": true } }, "required": [ "type", "id", "name", "input" ] } ] } }, "stop_reason": { "type": [ "string", "null" ], "enum": [ "end_turn", "max_tokens", "tool_use", "refusal", null ], "description": "Stop reason. `end_turn`: finished naturally (including a `stop_sequences` match); `max_tokens`: reached the max_tokens limit; `tool_use`: the model issued a tool call; `refusal`: content safety review was triggered." }, "stop_sequence": { "type": [ "string", "null" ], "description": "The stop sequence that was matched" }, "usage": { "type": "object", "description": "Token usage", "properties": { "input_tokens": { "type": "integer", "description": "Input tokens (excluding cache hits and cache writes). Total input = input_tokens + cache_read_input_tokens + cache_creation_input_tokens" }, "output_tokens": { "type": "integer", "description": "Output tokens (including reasoning tokens)" }, "cache_read_input_tokens": { "type": "integer", "description": "Input tokens served from cache" }, "cache_creation_input_tokens": { "type": "integer", "description": "Input tokens written to cache" }, "cache_creation": { "type": "object", "description": "Cache write breakdown by TTL", "properties": { "ephemeral_5m_input_tokens": { "type": "integer", "description": "Input tokens written to the 5-minute cache tier" }, "ephemeral_1h_input_tokens": { "type": "integer", "description": "Input tokens written to the 1-hour cache tier" } }, "required": [ "ephemeral_5m_input_tokens", "ephemeral_1h_input_tokens" ] }, "output_tokens_details": { "type": "object", "properties": { "thinking_tokens": { "type": "integer", "description": "The portion of output tokens used for reasoning" } } } } } } }, "MessagesStreamEvent": { "oneOf": [ { "title": "message_start", "type": "object", "properties": { "type": { "type": "string", "enum": [ "message_start" ] }, "message": { "$ref": "#/components/schemas/MessagesResponse" } }, "required": [ "type", "message" ] }, { "title": "content_block_start", "type": "object", "properties": { "type": { "type": "string", "enum": [ "content_block_start" ] }, "index": { "type": "integer" }, "content_block": { "oneOf": [ { "title": "thinking", "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking" ] }, { "title": "text", "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "title": "tool_use", "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_use" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": true } }, "required": [ "type", "id", "name", "input" ] } ] } }, "required": [ "type", "index", "content_block" ] }, { "title": "content_block_delta", "type": "object", "properties": { "type": { "type": "string", "enum": [ "content_block_delta" ] }, "index": { "type": "integer" }, "delta": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text_delta", "thinking_delta", "signature_delta", "input_json_delta" ] }, "text": { "type": "string", "description": "Text fragment for `text_delta`" }, "thinking": { "type": "string", "description": "Reasoning fragment for `thinking_delta`" }, "signature": { "type": "string", "description": "Signature for `signature_delta`" }, "partial_json": { "type": "string", "description": "Partial JSON of the tool input for `input_json_delta`; concatenate before parsing" } }, "required": [ "type" ] } }, "required": [ "type", "index", "delta" ] }, { "title": "content_block_stop", "type": "object", "properties": { "type": { "type": "string", "enum": [ "content_block_stop" ] }, "index": { "type": "integer" } }, "required": [ "type", "index" ] }, { "title": "message_delta", "type": "object", "properties": { "type": { "type": "string", "enum": [ "message_delta" ] }, "delta": { "type": "object", "properties": { "stop_reason": { "type": [ "string", "null" ], "enum": [ "end_turn", "max_tokens", "tool_use", "refusal", null ], "description": "Stop reason. `end_turn`: finished naturally (including a `stop_sequences` match); `max_tokens`: reached the max_tokens limit; `tool_use`: the model issued a tool call; `refusal`: content safety review was triggered." }, "stop_sequence": { "type": [ "string", "null" ] } } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Input tokens (excluding cache hits and cache writes). Total input = input_tokens + cache_read_input_tokens + cache_creation_input_tokens" }, "output_tokens": { "type": "integer", "description": "Output tokens (including reasoning tokens)" }, "cache_read_input_tokens": { "type": "integer", "description": "Input tokens served from cache" }, "cache_creation_input_tokens": { "type": "integer", "description": "Input tokens written to cache" }, "cache_creation": { "type": "object", "description": "Cache write breakdown by TTL", "properties": { "ephemeral_5m_input_tokens": { "type": "integer", "description": "Input tokens written to the 5-minute cache tier" }, "ephemeral_1h_input_tokens": { "type": "integer", "description": "Input tokens written to the 1-hour cache tier" } }, "required": [ "ephemeral_5m_input_tokens", "ephemeral_1h_input_tokens" ] }, "output_tokens_details": { "type": "object", "properties": { "thinking_tokens": { "type": "integer", "description": "The portion of output tokens used for reasoning" } } } } } }, "required": [ "type", "delta" ] }, { "title": "message_stop", "type": "object", "properties": { "type": { "type": "string", "enum": [ "message_stop" ] } }, "required": [ "type" ] } ], "description": "Streaming events. Each SSE frame's `event` matches `data.type`; the order is message_start → (content_block_start → content_block_delta… → content_block_stop)… → message_delta → message_stop." }, "MessagesErrorResponse": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type; see [Errors](/api/errors) for values" }, "message": { "type": "string", "description": "Error message describing the cause" } }, "required": [ "type", "message" ] }, "request_id": { "type": "string", "description": "Request ID; include it when reporting issues" } }, "required": [ "type", "error" ] } } }, "paths": { "/v1/models": { "get": { "summary": "List Models", "description": "List all currently available models.", "tags": [ "Models" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Model list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Model ID", "example": "kimi-k3" }, "object": { "type": "string", "example": "model" }, "created": { "type": "integer", "description": "Creation timestamp" }, "owned_by": { "type": "string", "example": "moonshot" }, "context_length": { "type": "integer", "description": "Maximum context length (tokens)" }, "supports_image_in": { "type": "boolean", "description": "Whether the model supports image input" }, "supports_video_in": { "type": "boolean", "description": "Whether the model supports video input" }, "supports_reasoning": { "type": "boolean", "description": "Whether the model supports deep thinking" } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/users/me/balance": { "get": { "summary": "Check Balance", "description": "REST API to check your available, voucher, and cash balances on Kimi OpenPlatform.", "tags": [ "Billing" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Balance information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/files": { "post": { "summary": "Upload File", "description": "Uploads a file for content extraction, image understanding, or video understanding. file-extract only supports content extraction from text-based files (such as pdf, doc, txt); for image understanding, use purpose=image.", "tags": [ "Files" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload" }, "purpose": { "type": "string", "enum": [ "file-extract", "image", "video", "batch" ], "description": "Specifies how the uploaded file will be processed. file-extract: extract content from text-based files (such as pdf, doc, txt); images are not supported; image: upload images for vision understanding; video: upload videos for video understanding; batch: upload JSONL files for batch processing" } }, "required": [ "file", "purpose" ] } } } }, "responses": { "200": { "description": "Uploaded file metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" } } } }, "400": { "description": "Bad request - Invalid upload parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "summary": "List Files", "description": "Lists all files uploaded by the current user.", "tags": [ "Files" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of uploaded files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileListResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/files/{file_id}": { "get": { "summary": "Get File Information", "description": "Retrieves metadata for a specific uploaded file.", "tags": [ "Files" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The file identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Delete File", "description": "Deletes a previously uploaded file.", "tags": [ "Files" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The file identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deletion result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDeleteResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/files/{file_id}/content": { "get": { "summary": "Get File Content", "description": "Retrieves the extracted content for files uploaded with purpose `file-extract`, returned as Markdown-formatted text.", "tags": [ "Files" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The file identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Extracted file content", "content": { "text/plain": { "schema": { "type": "string", "description": "Extracted file content as Markdown-formatted text" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/chat/completions": { "post": { "summary": "Create Chat Completion", "description": "Creates a completion for the chat message. Supports standard chat, Partial Mode, and Tool Use (Function Calling).", "tags": [ "Chat" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Msh-Request-Nonce", "in": "header", "required": false, "description": "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](/api/signatures-verify).", "schema": { "type": "string", "minLength": 1, "example": "7d929748-0ae6-41c2-ab5d-a186498ad721" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/KimiK3ChatRequest" }, { "$ref": "#/components/schemas/KimiK27CodeChatRequest" }, { "$ref": "#/components/schemas/KimiK26ChatRequest" } ], "discriminator": { "propertyName": "model", "mapping": { "kimi-k3": "#/components/schemas/KimiK3ChatRequest", "kimi-k2.7-code": "#/components/schemas/KimiK27CodeChatRequest", "kimi-k2.7-code-highspeed": "#/components/schemas/KimiK27CodeChatRequest", "kimi-k2.6": "#/components/schemas/KimiK26ChatRequest" } } } } } }, "responses": { "200": { "description": "Chat completion response", "headers": { "Msh-Request-Timestamp": { "description": "Unix timestamp in milliseconds at which the Kimi API accepted this request. Only returned when the request carries a valid `X-Msh-Request-Nonce`.", "schema": { "type": "integer", "format": "int64", "example": 1786338000123 } }, "Msh-Request-Signature": { "description": "Signature token prefixed with `reqsigv1_`, issued by the Kimi API over the nonce, timestamp, and the request's `model`; verify it with `POST /v1/signatures/verify`. Only returned when the request carries a valid `X-Msh-Request-Nonce`.", "schema": { "type": "string", "example": "reqsigv1_" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ChatCompletionChunk" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/responses": { "post": { "summary": "Create a model response", "description": "Creates a model response. Provide text or image inputs to generate text or JSON outputs. Have the model call the function tools you define. When `stream` is `true`, the response is delivered as a stream of SSE events.", "tags": [ "Responses" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Msh-Request-Nonce", "in": "header", "required": false, "description": "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](/api/signatures-verify).", "schema": { "type": "string", "minLength": 1, "example": "7d929748-0ae6-41c2-ab5d-a186498ad721" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesRequest" } } } }, "responses": { "200": { "description": "The response was created", "headers": { "Msh-Request-Timestamp": { "description": "Unix timestamp in milliseconds at which the Kimi API accepted this request. Only returned when the request carries a valid `X-Msh-Request-Nonce`.", "schema": { "type": "integer", "format": "int64", "example": 1786338000123 } }, "Msh-Request-Signature": { "description": "Signature token prefixed with `reqsigv1_`, issued by the Kimi API over the nonce, timestamp, and the request's `model`; verify it with `POST /v1/signatures/verify`. Only returned when the request carries a valid `X-Msh-Request-Nonce`.", "schema": { "type": "string", "example": "reqsigv1_" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsesResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ResponsesStreamEvent" } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - the API key is invalid or missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access to the resource is forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited or out of quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/anthropic/v1/messages": { "post": { "summary": "Messages API", "description": "Call Kimi models with an Anthropic Messages API compatible format, supporting streaming, tool use, image input, thinking, and structured output.", "tags": [ "Messages" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Msh-Request-Nonce", "in": "header", "required": false, "description": "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](/api/signatures-verify).", "schema": { "type": "string", "minLength": 1, "example": "7d929748-0ae6-41c2-ab5d-a186498ad721" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesRequest" } } } }, "responses": { "200": { "description": "Message response", "headers": { "Msh-Request-Timestamp": { "description": "Unix timestamp in milliseconds at which the Kimi API accepted this request. Only returned when the request carries a valid `X-Msh-Request-Nonce`.", "schema": { "type": "integer", "format": "int64", "example": 1786338000123 } }, "Msh-Request-Signature": { "description": "Signature token prefixed with `reqsigv1_`, issued by the Kimi API over the nonce, timestamp, and the request's `model`; verify it with `POST /v1/signatures/verify`. Only returned when the request carries a valid `X-Msh-Request-Nonce`.", "schema": { "type": "string", "example": "reqsigv1_" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/MessagesStreamEvent" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesErrorResponse" } } } } } } }, "/v1/tokenizers/estimate-token-count": { "post": { "summary": "Estimate Token Count", "description": "Estimates the number of tokens that would be used for a given set of messages and model. The input structure is almost identical to that of chat completion.", "tags": [ "Utilities" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateTokenRequest" } } } }, "responses": { "200": { "description": "Token count estimation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateTokenResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/signatures/verify": { "post": { "summary": "Verify Request Signature", "description": "Verifies a request signature returned in the response headers of the Chat Completions, Responses, or Messages API, proving that the request was handled by the Kimi API for the specified model rather than routed elsewhere. Submit the nonce used in the call, the timestamp from the response headers, the request's model, and the signature; the endpoint returns `valid: true` when the signature matches these three attributes exactly, and `valid: false` otherwise.", "tags": [ "Utilities" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureVerifyRequest" } } } }, "responses": { "200": { "description": "Verification result", "headers": { "Cache-Control": { "description": "Always `no-store`; verification results must not be cached.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureVerifyResponse" } } } }, "400": { "description": "Bad request - Invalid parameters or missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/tools/search": { "post": { "summary": "Web Search Basic", "description": "Run a web search and get structured results with title, snippet, site, and URL. You are charged once per successful call that returns at least one result; failed or empty-result calls are free. See [WebSearch Pricing](/pricing/tools).", "tags": [ "Tools" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsSearchRequest" } } } }, "responses": { "200": { "description": "Search results", "headers": { "X-Msh-Track-Id": { "description": "Request ID. If the client sends this header, its value is reused; otherwise the server generates one. Provide this ID when troubleshooting.", "schema": { "type": "string" } }, "X-Msh-Chat-Id": { "description": "Session ID, always `toolgw-{X-Msh-Track-Id}`; provide both IDs when troubleshooting.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsSearchResponse" } } } }, "400": { "description": "Bad request - Invalid parameters or missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key (status code only, no error body)" }, "403": { "description": "Forbidden - account inactive or suspended (status code only, no error body)" }, "408": { "description": "Client canceled the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate or concurrency limit exceeded, or rate-limit service temporarily unavailable", "headers": { "X-RateLimit-Limit": { "description": "The rate limit that was hit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Remaining quota in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "When the rate-limit window resets (Unix timestamp in seconds; returned when a per-second rate limit is hit).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Service temporarily unavailable; retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Request timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/tools/search_pro": { "post": { "summary": "Web Search Pro", "description": "Web Search Basic with site and time-range constraints, plus structured content chunks (`chunks`) for each result. You are charged once per successful call that returns at least one result; failed or empty-result calls are free. See [WebSearch Pricing](/pricing/tools).", "tags": [ "Tools" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsSearchProRequest" } } } }, "responses": { "200": { "description": "Search results with content snippets", "headers": { "X-Msh-Track-Id": { "description": "Request ID. If the client sends this header, its value is reused; otherwise the server generates one. Provide this ID when troubleshooting.", "schema": { "type": "string" } }, "X-Msh-Chat-Id": { "description": "Session ID, always `toolgw-{X-Msh-Track-Id}`; provide both IDs when troubleshooting.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsSearchProResponse" } } } }, "400": { "description": "Bad request - Invalid parameters or missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key (status code only, no error body)" }, "403": { "description": "Forbidden - account inactive or suspended (status code only, no error body)" }, "408": { "description": "Client canceled the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate or concurrency limit exceeded, or rate-limit service temporarily unavailable", "headers": { "X-RateLimit-Limit": { "description": "The rate limit that was hit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Remaining quota in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "When the rate-limit window resets (Unix timestamp in seconds; returned when a per-second rate limit is hit).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Service temporarily unavailable; retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Request timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/tools/fetch": { "post": { "summary": "URL Fetch", "description": "Fetch the content of a URL and get the page title and body text in Markdown (text and images concatenated in order). Only http and https URLs are supported. You are charged once per successful call that extracts content; failed or empty-content calls are free. See [WebSearch Pricing](/pricing/tools).", "tags": [ "Tools" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsFetchRequest" } } } }, "responses": { "200": { "description": "Fetch result", "headers": { "X-Msh-Track-Id": { "description": "Request ID. If the client sends this header, its value is reused; otherwise the server generates one. Provide this ID when troubleshooting.", "schema": { "type": "string" } }, "X-Msh-Chat-Id": { "description": "Session ID, always `toolgw-{X-Msh-Track-Id}`; provide both IDs when troubleshooting.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsFetchResponse" } } } }, "400": { "description": "Bad request - Invalid parameters or malformed URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key (status code only, no error body)" }, "403": { "description": "Forbidden - account inactive or suspended (no error body), or the URL was blocked by security risk control (returns a security_risk error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No extractable content found for the URL (markdown_not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Client canceled the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate or concurrency limit exceeded, or rate-limit service temporarily unavailable", "headers": { "X-RateLimit-Limit": { "description": "The rate limit that was hit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Remaining quota in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "When the rate-limit window resets (Unix timestamp in seconds; returned when a per-second rate limit is hit).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Service temporarily unavailable; retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Request timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/batches": { "post": { "summary": "Create Batch", "description": "Create a batch task. You need to first upload a JSONL file with purpose=\"batch\" via the Files API, then use the returned file_id to create the task.", "tags": [ "Batch" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } } }, "responses": { "200": { "description": "The created batch task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchObject" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "summary": "List Batches", "description": "List batch tasks for your organization.", "tags": [ "Batch" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Pagination cursor, pass the ID of the last batch from the previous page", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results per page, default 20", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of batch tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchListResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/batches/{batch_id}": { "get": { "summary": "Retrieve Batch", "description": "Retrieve the status and details of a specific batch task.", "tags": [ "Batch" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "description": "The ID of the batch task", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchObject" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Batch task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/batches/{batch_id}/cancel": { "post": { "summary": "Cancel Batch", "description": "Cancel an in-progress batch task. The status will change to cancelling and then to cancelled. Only tasks in validating, in_progress, or finalizing status can be cancelled.", "tags": [ "Batch" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "description": "The ID of the batch task", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The cancelled batch task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchObject" } } } }, "400": { "description": "Bad request - Task status does not allow cancellation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Batch task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": {} }