Kimi API: setup, examples and common errors

2. Make a first Python request

Install or update the compatible SDK in your Python environment:

python -m pip install --upgrade openai

Set MOONSHOT_API_KEY through your environment or secret manager, then save and run this script. It fails immediately if the variable is missing.

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": "Explain a context window in two short sentences."
    }],
    reasoning_effort="low",
    max_completion_tokens=4096,
)

choice = response.choices[0]
print(choice.message.content or "No final answer returned.")
print("Finish reason:", choice.finish_reason)
print("Usage:", response.usage)

K3 always thinks. The example selects low effort and an explicit output ceiling; the ceiling includes thinking and the answer. It is not a guarantee of a complete answer or an exact spending cap. If the finish reason is length, review the task and budget before increasing it. Sampling settings are omitted because K3 fixes parameters such as temperature. Source: official K3 quickstart.

Automatic retries are disabled here to make the first diagnostic call easier to follow. In an application, add bounded retries for transient failures rather than an unlimited loop.

3. The same request with cURL

This example uses Bash-style quoting on Linux, macOS or a Bash terminal. The key must already be available in the environment.

curl --fail-with-body --max-time 120 \
  "https://api.moonshot.ai/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "kimi-k3",
    "messages": [{
      "role": "user",
      "content": "Explain a context window in two short sentences."
    }],
    "reasoning_effort": "low",
    "max_completion_tokens": 4096
  }'

Expect a JSON response containing choices and usage information. The wording of a generated answer varies. A local timeout does not prove that the provider stopped processing the request; check usage records before retrying blindly. See the platform quickstart and billing troubleshooting.

Example status: documentation-based examples, reviewed for syntax and configuration. No authenticated live inference test or latency benchmark was performed by ChinaAI for this guide.

Before adding chat, files or tools

Build a server endpoint that controls access, request size, per-user usage and total application spend. Record the selected model, finish reason, token use and a request identifier when available. Keep secrets and unnecessary prompt contents out of logs.

For K3 multi-turn and tool workflows, preserve the complete returned assistant message. For vision, follow the documented base64 or uploaded-file format; ordinary public image URLs are not supported by the K3 guide. Do not assume a generic OpenAI-compatible image example works unchanged.

Streaming can improve how progress is displayed, but it requires handling partial content, cancellation and errors. Add it after the basic request succeeds. Kimi’s current help page also flags built-in web search documentation as being updated; verify that feature’s current status before relying on it.

Changing to K2.6 or K2.7 Code requires checking their own parameters. Use our Kimi model comparison before replacing the model name.