# Kimi K3 API

> Frontier coding, native vision, and 1M-token agents from Moonshot AI.

- **Provider**: Moonshot AI
- **Model id**: `kimi-k3`
- **Modality**: text
- **Price**: 239–1195 credits

## Overview

Kimi K3 is called in ONE step: POST your request and the answer comes back in the same response, in `text`. There is no task to poll.

## Authentication

All requests require a Bearer Token in the request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Create Task

`POST https://you.bot/api/v1/generate`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| modelId | string | Yes | Model id: `kimi-k3` |
| input | object | Yes | Input parameters object (see below) |
| callbackUrl | string | No | https URL we POST the finished task to. Signed with `X-Webhook-Signature` once you create a webhook signing key in Dashboard → Settings |

### input object parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string | Yes | Text value (example: Refactor this into an iterative version and explain the trade-off: a recursive directory walk that returns every file path under a root, currently blowing the… — full value in the request example) |
| reasoning_effort | string | No | Control reasoning depth: Low for faster responses, High for deeper analysis (options: Low \| Medium \| High \| XHigh) (example: High) |
| max_tokens | number | No | Maximum response length. Kimi K3 supports a 1M-token context; leave empty for the default of 4096. (range 1-128000) |
| stream | boolean | No | Turn off to get a single non-streaming response. (true/false) (example: true) |
| system | string | No | System instruction for the model. Defaults to "You are Kimi K3, developed by Moonshot AI." when omitted. |
| messages | array | No | A conversation instead of a single `prompt`: an array of { "role", "content" } objects, where role is user, assistant, system or tool (a function result, with `tool_call_id`); an assistant message may carry `tool_calls` instead of text — see `tools`. Send the whole conversation — we do not limit how many messages it has, and we do not drop old ones; the model's context window is the limit. Send `prompt` or `messages`, not both. Do not flatten a conversation into one prompt with "User:" / "Assistant:" labels — the model reads that as a single message, and a model using web search then searches for the whole block instead of your question. |
| tools | array | No | Functions the model may call, up to 64. Each is { "type": "function", "function": { "name", "description", "parameters" } } with `parameters` a JSON Schema object (the flat Responses form and Anthropic's { "name", "description", "input_schema" } are accepted too); `strict: true` is not accepted on this model. When the model calls one, the response carries `toolCalls`: run the function, then send the conversation back in `messages` with the assistant's `tool_calls` and one { "role": "tool", "tool_call_id", "content" } message per result — and the same `tools` again. Function calling cannot be combined with web search in the same request. |
| tool_choice | string \| object | No | `auto` (the model decides; the default when `tools` is set), `none` (no call), or `required` (at least one call). Other values are not available on this model and are refused before any charge. |

### Request example

```json
{
  "modelId": "kimi-k3",
  "input": {
    "prompt": "Refactor this into an iterative version and explain the trade-off: a recursive directory walk that returns every file path under a root, currently blowing the stack on deep trees. Give the rewritten function, then three sentences on what you gained, what you gave up, and the input size where the difference starts to matter.",
    "reasoning_effort": "High",
    "max_tokens": 4096,
    "stream": false
  }
}
```

### Response example

```json
{
  "model": "kimi-k3",
  "text": "…",
  "creditsCharged": 0.48,
  "usage": {
    "inputTokens": 1400,
    "outputTokens": 120,
    "cachedInputTokens": 0,
    "cacheWriteTokens": 0
  }
}
```

## Query Task

`GET https://you.bot/api/v1/task/{taskId}?model=kimi-k3`

When `state` is `success`, the output is in `resultUrls`: `{ "text": "…" }`. (Text models return inline in the create response.)

## Error Codes

| Code | Description |
|------|-------------|
| 200 | Request successful |
| 400 | Invalid request parameters |
| 401 | Authentication failed — check API Key |
| 402 | Insufficient account balance |
| 403 | IP not allowed for this key, or the key is restricted to other models |
| 404 | Task not found, or it has expired |
| 409 | Duplicate request — an identical submit arrived moments ago. Nothing was charged; retry is safe |
| 413 | Payload too large — see the character and file-size limits for this model |
| 429 | Rate limit exceeded — retry after the Retry-After header |
| 500 | Internal server error |
| 504 | Upstream timed out — nothing was delivered; retry is safe |
| 400 · capability_not_supported | A capability was requested (e.g. `web_search: true`) that this model does not offer — refused, nothing charged |
| 400 · unknown_image_field | Images were sent under a key this model has no parameter for (input_urls, image_urls, imageUrl …) — refused rather than answered without them |
| 400 · image_input_not_supported | This model accepts text only — a request with an image is refused, not answered without it |
| 400 · tools_invalid | `tools` is malformed (not an array, a non-function tool, a bad or repeated name, parameters that are not an object schema), or a conversation with function calls was sent without `tools` — refused, nothing charged |
| 400 · tool_choice_invalid | `tool_choice` is malformed, names a function that is not in `tools`, or forces a call while `tools` is empty — refused, nothing charged |
| 400 · message_tool_call_invalid | An assistant `tool_calls` entry or a `tool` message is malformed, or a call and its result do not pair up (every call needs its own tool message right after it) — refused, nothing charged |
| 400 · message_tool_block_unsupported | A `tool_use` or `tool_result` content block was sent; send calls as `tool_calls` and results as `tool` messages instead |