Kimi API: Access, Rate Limits & SDKs 2026

The raw HTTP call: one POST with a bearer key, the model id kimi-k3, a messages array, and a cap on how long the reply may run. Handy for a smoke test or a language the SDK does not cover.

curl https://api.moonshot.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Summarize the architecture of this repository."}],
    "max_completion_tokens": 4096
  }'

The same call through the official OpenAI SDK. Point base_url at Moonshot and read the key from the environment. The reply text is in choices[0].message.content, and usage.cached_tokens reports how much input was served from cache.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Summarize the architecture of this repository."},
    ],
    max_completion_tokens=4096,
)

print(response.choices[0].message.content)
print(response.usage.cached_tokens)

The Node SDK version: identical request, async/await. Node 18 or newer and openai 1.0 or newer are all you need.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MOONSHOT_API_KEY,
  baseURL: "https://api.moonshot.ai/v1",
});

const response = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [
    { role: "user", content: "Summarize the architecture of this repository." },
  ],
  max_completion_tokens: 4096,
});

console.log(response.choices[0].message.content);

Reuse a long system prefix across questions. The first call has nothing to reuse (cached_tokens is 0); the second, with the same prefix first, bills those shared tokens at the cache-hit rate of $0.30 per 1M.

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.ai/v1")

# A long, unchanging block: a handbook, a schema, a system prompt. Load it once.
HANDBOOK = open("handbook.md").read()

def ask(question: str):
    return client.chat.completions.create(
        model="kimi-k3",
        messages=[
            {"role": "system", "content": HANDBOOK},  # first and byte-for-byte identical
            {"role": "user", "content": question},
        ],
        max_completion_tokens=2048,
    )

cold = ask("What does chapter 3 cover?")
print(cold.usage.cached_tokens)   # 0: nothing to reuse yet

warm = ask("And chapter 4?")
print(warm.usage.cached_tokens)   # shared prefix now bills at $0.30 / 1M, not $3.00

The Node version of the same pattern: load the fixed context once, keep it first in messages, and read cached_tokens off usage to confirm the hit.

import OpenAI from "openai";
import { readFileSync } from "node:fs";

const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: "https://api.moonshot.ai/v1" });

const HANDBOOK = readFileSync("handbook.md", "utf8"); // long, unchanging context

async function ask(question: string) {
  return client.chat.completions.create({
    model: "kimi-k3",
    messages: [
      { role: "system", content: HANDBOOK }, // first and identical on every call
      { role: "user", content: question },
    ],
    max_completion_tokens: 2048,
  });
}

const cold = await ask("What does chapter 3 cover?");
console.log(cold.usage?.cached_tokens); // 0 on the cold call

const warm = await ask("And chapter 4?");
console.log(warm.usage?.cached_tokens); // shared prefix now bills at the cache-hit rate

Over raw HTTP there is nothing to configure. Send the fixed context in the system message and keep it identical on the next call; the shared prefix bills at $0.30 per 1M.

# Put the long, fixed context in the system message and keep it identical between calls.
# The next call that reuses this prefix bills the shared tokens at $0.30 / 1M.
curl https://api.moonshot.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "system", "content": "<long, unchanging handbook text>"},
      {"role": "user", "content": "What does chapter 3 cover?"}
    ],
    "max_completion_tokens": 2048
  }'

Define one tool, force a call with tool_choice required, read the arguments off tool_calls, run the function, then hand the result back as a role:tool message and call again for the final answer.

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Look up the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
            "additionalProperties": False,
        },
        # strict defaults to true: arguments are constrained to this schema (MFJS)
    },
}]

messages = [{"role": "user", "content": "What is the weather in Beijing right now?"}]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="required",   # force a call; only K3 accepts "required"
    max_completion_tokens=1024,
)

call = first.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)
# run get_weather(**args) yourself, then hand the result back:

messages.append(first.choices[0].message)          # return the assistant turn unchanged
messages.append({
    "role": "tool",
    "tool_call_id": call.id,                        # must match the call
    "content": json.dumps({"tempC": 29, "sky": "clear"}),
})

final = client.chat.completions.create(model="kimi-k3", messages=messages, tools=tools, max_completion_tokens=1024)
print(final.choices[0].message.content)

The same round-trip in TypeScript. Note tool_choice required, which only K3 accepts, and that the assistant turn is pushed back onto messages unchanged before the tool result.

const tools = [{
  type: "function" as const,
  function: {
    name: "get_weather",
    description: "Look up the current weather for a city.",
    parameters: {
      type: "object",
      properties: { city: { type: "string" } },
      required: ["city"],
      additionalProperties: false,
    },
  },
}];

const messages: any[] = [{ role: "user", content: "What is the weather in Beijing right now?" }];

const first = await client.chat.completions.create({
  model: "kimi-k3",
  messages,
  tools,
  tool_choice: "required", // only K3 accepts "required"
  max_completion_tokens: 1024,
});

const call = first.choices[0].message.tool_calls![0];
const args = JSON.parse(call.function.arguments);
// run getWeather(args) yourself, then return the result:

messages.push(first.choices[0].message);
messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify({ tempC: 29, sky: "clear" }) });

const final = await client.chat.completions.create({ model: "kimi-k3", messages, tools, max_completion_tokens: 1024 });
console.log(final.choices[0].message.content);

The opening request over HTTP. The reply carries finish_reason tool_calls; you then POST a follow-up that adds a role:tool message with your function's result.

# The reply comes back with finish_reason "tool_calls" and the arguments to run.
# You execute the function, then POST a follow-up that adds a {"role":"tool",...} message.
curl https://api.moonshot.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "What is the weather in Beijing right now?"}],
    "tool_choice": "required",
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Look up the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }],
    "max_completion_tokens": 1024
  }'

Read a PNG, base64-encode it, and send it as an image_url part alongside a text part. The content is a list, not a string, which is what makes it a vision request. No cURL tab for this one: a base64 payload inside a shell body is unreadable, so the walkthrough sticks to the SDKs.

import base64

with open("chart.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [   # content MUST be a list of parts, not a string
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
            {"type": "text", "text": "What trend does this chart show?"},
        ],
    }],
    max_completion_tokens=1024,
)
print(response.choices[0].message.content)

The Node version: base64 the file, then pass the array of parts. Same rule about content being an array of parts rather than a string.

import { readFileSync } from "node:fs";

const b64 = readFileSync("chart.png").toString("base64");

const response = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [{
    role: "user",
    content: [ // must be an array of parts, not a string
      { type: "image_url", image_url: { url: `data:image/png;base64,${b64}` } },
      { type: "text", text: "What trend does this chart show?" },
    ],
  }],
  max_completion_tokens: 1024,
});
console.log(response.choices[0].message.content);

Force a strict JSON object with json_schema. The nullable email union tells the model to return null when the field is absent rather than guessing, and only content is parsed.

import json

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "email": {"type": ["string", "null"]},   # nullable union: returns null, not a guess
    },
    "required": ["name", "email"],
    "additionalProperties": False,
}

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Pull the name and email from: Dana Ko, [email protected]"}],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "contact", "strict": True, "schema": schema},
    },
    max_completion_tokens=512,
)

data = json.loads(response.choices[0].message.content)  # parse .content only, never the whole object
print(data["name"], data["email"])

The TypeScript version. strict true plus additionalProperties false locks the shape; the sampler is constrained at decode time, so the reply parses cleanly.

const schema = {
  type: "object",
  properties: {
    name: { type: "string" },
    email: { type: ["string", "null"] }, // nullable union: returns null instead of a guess
  },
  required: ["name", "email"],
  additionalProperties: false,
};

const response = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [{ role: "user", content: "Pull the name and email from: Dana Ko, [email protected]" }],
  response_format: {
    type: "json_schema",
    json_schema: { name: "contact", strict: true, schema },
  },
  max_completion_tokens: 512,
});

const data = JSON.parse(response.choices[0].message.content!); // parse .content only
console.log(data.name, data.email);

The raw request. The json_schema block travels inside response_format; the model can only emit tokens that keep the output valid against it.

curl https://api.moonshot.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Pull the name and email from: Dana Ko, [email protected]"}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "contact",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {"name": {"type": "string"}, "email": {"type": ["string", "null"]}},
          "required": ["name", "email"],
          "additionalProperties": false
        }
      }
    },
    "max_completion_tokens": 512
  }'

Iterate the stream, print each delta as it lands, and read the final usage chunk, which is the only one that carries cached_tokens. include_usage is what makes that last chunk appear.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Explain B-trees in two short paragraphs."}],
    max_completion_tokens=1024,
    stream=True,
    stream_options={"include_usage": True},   # adds a final usage chunk with cached_tokens
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:                            # only the final chunk carries usage
        print("\ncached:", chunk.usage.cached_tokens)

The async-iterator version. Same idea: write deltas as they arrive, then pick up cached_tokens from the trailing usage chunk.

const stream = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [{ role: "user", content: "Explain B-trees in two short paragraphs." }],
  max_completion_tokens: 1024,
  stream: true,
  stream_options: { include_usage: true }, // final chunk carries usage + cached_tokens
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
  if (chunk.usage) console.log("\ncached:", chunk.usage.cached_tokens);
}

Over HTTP, stream true turns on SSE and -N keeps the socket open. You will see data: lines and a closing data: [DONE].

# -N keeps the connection open; the server sends "data:" lines and ends with "data: [DONE]".
curl -N https://api.moonshot.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Explain B-trees in two short paragraphs."}],
    "max_completion_tokens": 1024,
    "stream": true,
    "stream_options": {"include_usage": true}
  }'