# 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, Pricing, per-model pricing pages (K3, K2.7 Code, K2.6, K2.5, V1), Rate limits, Errors, Vision, Web search, Partial mode.

# 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).

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:

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):

• 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); minimum $1 to start:

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

Error body (errors doc):

{ "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:

{ "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.