Moonshot AI Kimi API (K3 / moonshot-v1 ecosystem)

1) What the Kimi API is

Moonshot AI's Open Platform (often called the "Kimi API") provides an HTTP API to interact with Moonshot/Kimi models: an ecosystem spanning long-context chat models, tool calling, multimodal vision, and - as of July 2026 - the frontier-scale Kimi K3.

2) Authentication & base URLs

Kimi API uses standard Bearer authentication: send your key in the Authorization header. Base URLs differ by region.

• Never place API keys in frontend JavaScript - always call Kimi API from your backend.
• Store keys in a secrets manager (or at least environment variables) and rotate periodically.
• Use request logging and per-user quotas to reduce abuse risk and prevent surprise billing.
• If you allow user-supplied prompts, add content filtering and "dangerous prompt" detection for your domain.
• Most accounts need a small minimum top-up (commonly cited around $1) before a newly created key becomes active.

curl "https://api.moonshot.ai/v1/models" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY"

3) OpenAI compatibility

A major advantage of the Kimi API ecosystem is compatibility with familiar "chat completions" request bodies - including for K3, which ships compatible with the OpenAI SDK. Migration usually comes down to four steps.

• Swap the base URL to https://api.moonshot.ai/v1 (or .cn).
• Replace the API key environment variable and header.
• Update the model string to a Moonshot/Kimi model ID (see Section 4).
• Review tool-calling parameter differences (legacy functions vs. modern tools).

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

{
  "model": "moonshot-v1-32k",
  "messages": [
    {"role":"system","content":"You are a helpful assistant."},
    {"role":"user","content":"Summarize this article in 6 bullets..."}
  ],
  "temperature": 0.3
}

4) Models & context windows

Moonshot's lineup now spans two generations: the moonshot-v1 family (context-size-named, general chat and vision) and the K-series agentic/reasoning models, which evolved rapidly through 2025–2026 from K2 to the frontier-scale K3.

5) Chat API

You send a list of messages (system, user, assistant) and receive a model-generated response. A production-grade chat layer usually includes safe prompt construction, streaming support, response validation, retries, and logging.

• system: set behavior ("You are a concise support agent."), output constraints, tone, policy.
• user: the user's input - ideally sanitized and length-checked.
• assistant: previous replies (conversation memory). Keep only what you need to control token usage.
• temperature: lower (0–0.3) for extraction/structured output; higher (0.7–1.0) for ideation. Use temperature or top_p, not both at once.
• Length control: request a specific shape ("Return exactly 6 bullets," "Return JSON with keys …") to reduce run-on outputs and keep costs predictable.

async function kimiChat({ prompt }) {
  const res = await fetch("https://api.moonshot.ai/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MOONSHOT_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "moonshot-v1-32k",
      messages: [
        { role: "system", content: "You are a concise developer assistant." },
        { role: "user", content: prompt }
      ],
      temperature: 0.2
    })
  });

  if (!res.ok) {
    const err = await res.text();
    throw new Error(`Kimi API error ${res.status}: ${err}`);
  }

  const data = await res.json();
  return data.choices?.[0]?.message?.content ?? "";
}

import os, requests

def kimi_chat(prompt: str) -> str:
    url = "https://api.moonshot.ai/v1/chat/completions"
    headers = {
        "Authorization": f"Bearer {os.environ['MOONSHOT_API_KEY']}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": "moonshot-v1-32k",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant. Keep answers under 150 words."},
            {"role": "user", "content": prompt},
        ],
        "temperature": 0.2,
    }
    r = requests.post(url, headers=headers, json=payload, timeout=60)
    r.raise_for_status()
    return r.json()["choices"][0]["message"]["content"]

6) Tool calling

Tool calling lets the model decide when to call external functions you define. The model outputs a structured tool-call object; your application executes the tool and returns the result back as a follow-up message.

1. Define tools with names, descriptions, and a JSON schema for parameters.
2. Send a chat request with tools included.
3. The model replies with normal text, or one or more tool_calls.
4. Your code executes the tool(s) securely and returns results as messages.
5. The model uses those results to produce the final user-facing response.

{
  "type": "function",
  "function": {
    "name": "search_kb",
    "description": "Search the internal knowledge base for relevant documents.",
    "parameters": {
      "type": "object",
      "properties": {
        "query": { "type": "string", "description": "Search query." },
        "top_k": { "type": "integer", "description": "Number of results.", "default": 5 }
      },
      "required": ["query"]
    }
  }
}

messages = [system, user]
tools = [search_kb, get_order_status, ...]
resp = chat(messages, tools, tool_choice="auto")

if resp contains tool_calls:
  for each call:
    args = validate(call.arguments)
    result = execute_tool(call.name, args)
    messages.append({role:"tool", tool_call_id: call.id, content: json(result)})
  resp2 = chat(messages, tools, tool_choice="auto")
  return resp2.final_answer
else:
  return resp.text

• Keep tools small and single-purpose (search, fetch, update).
• Use consistent output formats from tools (JSON).
• Add timeouts and retries around tool execution.
• Log every tool call for debugging and safety auditing.
• Add a "planner" instruction to encourage calling tools only when needed, not by habit.

7) Vision inputs

Moonshot's guides describe vision preview models - moonshot-v1-8k-vision-preview, moonshot-v1-32k-vision-preview, moonshot-v1-128k-vision-preview - alongside native vision now built into K2.5 and K3. These accept image input plus text for screenshot interpretation, chart explanation, UI analysis, and multimodal reasoning.

• Users upload screenshots wanting explanations ("Why is this build failing?" "What does this chart imply?").
• Document processing includes scanned pages where text extraction alone loses context.
• You want the assistant to interpret UI/UX mocks or design comps and generate code or copy.

8) Token estimation

Moonshot exposes an "Estimate Tokens" API to calculate token count for a request, including both plain text and visual input. This lets you warn users before an expensive request, auto-compress/trim context, and enforce budgets - increasingly important with K3's 1M-token window.

• Long user messages or pasted documents.
• Large RAG results that might overrun context.
• Multimodal messages with images.
• Agent loops that might chain many tool calls and assistant turns.

9) Files & attachments

Moonshot's API documentation includes a Files endpoint category. Even when "files" isn't the headline feature you need, file-handling in your application is common for a few reasons.

• Large documents you don't want to paste directly into messages.
• Repeatability: upload a file once, reference it many times.
• Auditing: keep track of which file influenced which answer.
• Security: store files under your own access control and share only safe excerpts.

10) Pricing & budgeting

Moonshot presents costs as price per 1M tokens, with input/output distinguished and a significant discount for cache-hit input - increasingly valuable with K3's long context window, where keeping stable prefixes (system prompts, tool definitions, document prefixes) unchanged across requests lets the cache do the work.

11) Rate limits & reliability

Like most AI APIs, Kimi API enforces rate limits and concurrency constraints, typically tiered by account recharge/spend level. Early or trial tiers can be strict - assume "Too Many Requests" (HTTP 429) will happen sometimes and handle it gracefully.

• Retries with backoff: on 429/5xx, wait and retry rather than hammer the API.
• Jitter: add randomness to backoff to avoid synchronized spikes.
• Queue: enqueue bursty user requests rather than firing immediately.
• Timeouts: set timeouts for API calls and tool executions; don't hang forever.
• Idempotency: avoid duplicate charges when users click "Send" multiple times.

delay = 1.5s
for attempt in 1..6:
  try:
    return call_kimi()
  except RateLimitError:
    sleep(delay + random(0..500ms))
    delay = min(delay * 1.8, 15s)
throw "rate-limited"

12) Production architecture

A scalable LLM system combines prompt design, backend orchestration, and observability. The UI calls your backend, your backend calls Kimi, a queue manages concurrency for heavy tasks, and your storage layer holds persistent artifacts.

• Collect real user queries (anonymized) and label good vs. bad outcomes.
• Create a small test suite for each feature ("support replies," "invoice extraction").
• Run offline evaluations: compare models, prompts, temperatures - including K2.x vs. K3 trade-offs.
• Ship changes behind a flag, monitor cost + satisfaction.
• Iterate and keep a changelog for transparency.

FAQ: Kimi API

Official documentation

Use these as the source of truth for schemas, model availability, pricing updates, and advanced guides - model names and rates move fast, especially in launch weeks.