<!--
  kimi.md
  Zyquo Cloud
  Author: Simon-Pierre Boucher
  Mail: contact@spboucher.ai
-->

# Kimi (Moonshot AI) — Provider Research

Research date: **2026-07-30**. Live `GET /v1/models` probe from `api.moonshot.ai` with a real key (12 models) is the authoritative ID list. Official docs now live at **platform.kimi.ai** (`platform.moonshot.ai` 301-redirects there): [Chat API](https://platform.kimi.ai/docs/api/chat.md), [Pricing](https://platform.kimi.ai/docs/pricing/chat), per-model pricing pages ([K3](https://platform.kimi.ai/docs/pricing/chat-k3.md), [K2.7 Code](https://platform.kimi.ai/docs/pricing/chat-k27-code.md), [K2.6](https://platform.kimi.ai/docs/pricing/chat-k26.md), [K2.5](https://platform.kimi.ai/docs/pricing/chat-k25.md), [V1](https://platform.kimi.ai/docs/pricing/chat-v1.md)), [Rate limits](https://platform.kimi.ai/docs/pricing/limits.md), [Errors](https://platform.kimi.ai/docs/api/errors.md), [Vision](https://platform.kimi.ai/docs/guide/use-kimi-vision-model.md), [Web search](https://platform.kimi.ai/docs/guide/use-web-search.md), [Partial mode](https://platform.kimi.ai/docs/guide/use-partial-mode-feature-of-kimi-api.md).

---

## 1. Base URL & Endpoints

- **Base URL (international — Zyquo Cloud uses this):** `https://api.moonshot.ai/v1`
- Chat completions: `POST /v1/chat/completions`
- Model listing: `GET /v1/models` (verified live today)
- Also available: token estimation endpoint (for pre-computing image/video token cost), files API (`ms://<file-id>` video refs), context caching, batch.
- **China variant:** `https://api.moonshot.cn/v1` — separate platform and keys. Keys are **not cross-platform**: an `.ai` key fails on `.cn` and vice versa (errors doc). Zyquo Cloud uses `.ai` only.

## 2. Authentication

Standard Bearer (confirmed):

```
Authorization: Bearer sk-...
```

## 3. Chat Model Catalog

All 12 models from the live probe are chat models (nothing to filter). Capability flags below come straight from the probe (`supports_image_in`, `supports_video_in`, `supports_reasoning`, `context_length`); pricing from the official per-model pricing pages (USD, per 1M tokens; input is billed by cache hit vs miss — automatic context caching is built in).

| API ID | Context | Vision | Video | Reasoning | In (cache hit / miss) | Out | Notes |
|---|---|---|---|---|---|---|---|
| `kimi-k3` | 1,048,576 | yes | yes | **always on** (`reasoning_effort`) | $0.30 / $3.00 | $15.00 | Flagship. Default max output 131,072, settable up to 1,048,576. Tools, JSON mode, structured output, partial mode, web search. **Recommended** |
| `kimi-k2.7-code` | 262,144 | yes | yes | always on (`thinking: {"type":"enabled","keep":"all"}`) | $0.19 / $0.95 | $4.00 | Dedicated coding/agent model. **Recommended for code** |
| `kimi-k2.7-code-highspeed` | 262,144 | yes | yes | always on | $0.38 / $1.90 | $8.00 | Same model, ~180 tok/s (up to 260 tok/s short-context) |
| `kimi-k2.6` | 262,144 | yes | yes | hybrid (`thinking: {"type":"enabled"\|"disabled","keep":null\|"all"}`) | $0.16 / $0.95 | $4.00 | Tools, JSON mode, partial mode, web search |
| `kimi-k2.5` | 262,144 | yes | yes | hybrid (`thinking: {"type":"enabled"\|"disabled"}`) | $0.10 / $0.60 | $3.00 | Cheapest K-series |
| `moonshot-v1-8k` | 8,192 | no | no | no | $0.20 | $2.00 | Legacy "classic" series |
| `moonshot-v1-32k` | 32,768 | no | no | no | $1.00 | $3.00 | Legacy |
| `moonshot-v1-128k` | 131,072 | no | no | no | $2.00 | $5.00 | Legacy |
| `moonshot-v1-auto` | 131,072 | no | no | no | billed as selected size (unverified) | | Auto-routes to 8k/32k/128k by context length |
| `moonshot-v1-8k-vision-preview` | 8,192 | yes | no | no | $0.20 | $2.00 | Legacy vision |
| `moonshot-v1-32k-vision-preview` | 32,768 | yes | no | no | $1.00 | $3.00 | Legacy vision |
| `moonshot-v1-128k-vision-preview` | 131,072 | yes | no | no | $2.00 | $5.00 | Legacy vision |

No dated snapshots exist in the live catalog. Max output for K2.x/moonshot-v1 not documented separately from the context window (unverified). moonshot-v1 cache-hit pricing not published (single input price).

## 4. Request / Response Format

Fully **OpenAI-compatible**. Minimal request:

```json
POST https://api.moonshot.ai/v1/chat/completions
Authorization: Bearer sk-...
Content-Type: application/json

{
  "model": "kimi-k3",
  "messages": [{ "role": "user", "content": "Hello" }]
}
```

Response: standard `chat.completion`. Deviations / additions (from [chat API doc](https://platform.kimi.ai/docs/api/chat.md)):

- `choices[0].message.reasoning_content` — "returned only when thinking mode is enabled". `finish_reason`: `stop | length | tool_calls`.
- `usage` includes `cached_tokens` (automatic context caching).
- Vision content parts: `{"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}` — content must be a real JSON array, "do not serialize the JSON array … as a string". Video via `{"type":"video_url","video_url":{"url":"ms://<file-id>"}}` (uploaded to Moonshot storage first). Recommended limits: images ≤ 4096×2160, video ≤ 1920×1080, request body ≤ 100 MB.
- Prefer `max_completion_tokens` over `max_tokens` (K3 default 131,072, max 1,048,576).
- `response_format`: `{"type":"text"}` (default), `{"type":"json_object"}`, `{"type":"json_schema","json_schema":{...}}` (structured output).

## 5. Streaming (SSE)

`"stream": true` → standard SSE: each event line is `data: {json}`; terminates with `data: [DONE]`. `stream_options: {"include_usage": true}` puts complete usage in the final chunk. Thinking models stream `delta.reasoning_content` before `delta.content` — map to Zyquo Cloud's collapsible thinking section. Tool-call deltas follow the OpenAI incremental `tool_calls` convention.

## 6. Special Parameters

- **Sampling params are documented for moonshot-v1 only** (chat API doc): `temperature` 0–1 (default 0 — Moonshot's historic cap of 1 still holds), `top_p` 0–1 (default 1), `n` 1–5, `presence_penalty`/`frequency_penalty` −2.0–2.0. For K-series models the docs expose reasoning controls instead — Zyquo Cloud should hide/limit sampling controls per model accordingly.
- **Reasoning controls:**
  - `kimi-k3`: `reasoning_effort`: `"low" | "high" | "max"` (default `"max"`); "Kimi K3 always enables thinking with Preserved Thinking".
  - `kimi-k2.6`: `thinking: {"type":"enabled"|"disabled","keep":null|"all"}`; `kimi-k2.5`: `thinking: {"type":"enabled"|"disabled"}`; `kimi-k2.7-code`: always `{"type":"enabled","keep":"all"}`.
- **Partial mode** (assistant prefill): append `{"role":"assistant","content":"Dear customer, hello,","partial":true}` as the last message; the model continues from the prefix (client must concatenate). Use cases: forced openings, resuming `finish_reason=length` truncations (include prior `reasoning_content` when resuming thinking output), role-play consistency via `name` field.
- **Built-in web search tool:** declare `{"type":"builtin_function","function":{"name":"$web_search"}}` (the `$` prefix marks Kimi built-ins). Model emits a tool call; search runs server-side; echo the tool result back as a `role: tool` message. Charged a per-call fee on top of tokens; search-result tokens count toward `prompt_tokens`. Supported on `kimi-k3` and `kimi-k2.6` (with reasoning enabled). **Caution (2026-07-30):** K3 pricing page says `web_search` "is currently being updated" and recommends against using it right now.
- `prompt_cache_key` (cache-hit optimization), `safety_identifier` (hashed end-user ID), `tool_choice` (`auto|none|required|{function}`), `stop` (≤5 strings, ≤32 bytes each).

## 7. Rate Limits & Errors

Tiers by **cumulative recharge** ([limits doc](https://platform.kimi.ai/docs/pricing/limits.md)); minimum $1 to start:

| Tier | Recharge | Concurrency | RPM | TPM | TPD |
|---|---|---|---|---|---|
| 0 | $1 | 1 | 3 | 500K | 1.5M |
| 1 | $10 | 50 | 200 | 2M | ∞ |
| 2 | $20 | 100 | 500 | 3M | ∞ |
| 3 | $100 | 200 | 5,000 | 3M | ∞ |
| 4 | $1,000 | 400 | 5,000 | 4M | ∞ |
| 5 | $3,000 | 1,000 | 10,000 | 5M | ∞ |

Higher limits: api-service@moonshot.ai. No per-model limits.

Error body ([errors doc](https://platform.kimi.ai/docs/api/errors.md)):

```json
{ "error": { "type": "error_type_string", "message": "Human-readable description" } }
```

Key types: 401 `invalid_authentication_error` / `incorrect_api_key_error`; 400 `invalid_request_error` (incl. "Input token length too long") and `content_filter`; **429 covers two distinct cases** — `exceeded_current_quota_error` ("Account balance is insufficient" — do NOT retry, tell the user to top up) vs `rate_limit_reached_error` (back off and retry); 500/503/504 `server_error` / `server_unavailable` (retry with backoff). Zyquo Cloud must branch on `error.type`, not just HTTP status.

## 8. `/models` Listing

**Yes.** `GET https://api.moonshot.ai/v1/models` — OpenAI list shape **plus rich extension fields**, verified live:

```json
{ "object": "list", "data": [ {
  "id": "kimi-k3", "object": "model", "created": 1785311147, "owned_by": "moonshot",
  "permission": [ { "...": "..." } ],
  "supports_image_in": true, "supports_video_in": true,
  "supports_reasoning": true, "context_length": 1048576 } ] }
```

The extras (`supports_image_in`, `supports_video_in`, `supports_reasoning`, `context_length`) let Zyquo Cloud derive capabilities dynamically at refresh time — the only one of the three providers in this batch that exposes capability metadata.