The Moonshot API remains compatible with the OpenAI interface, but two things changed in 2026: the console moved to the Kimi API open platform, and the entire moonshot-v1 family was retired on August 31. Old projects that copy their old configuration often get either a 401 or a 404 model_not_found. This article follows the order "choose the site, choose the model, get a call working, then migrate." Models and prices follow the model pricing page.

Note: Moonshot and Kimi are trademarks of their respective owners. This article is a technical integration guide only. Model lists, context lengths, and parameter rules may change, so refer to the current official documentation.

1. The Entry Point Changed; the API Domain Did Not

platform.moonshot.cn now redirects to platform.kimi.com, and the international site platform.moonshot.ai redirects to platform.kimi.ai. The console, account, balance, and keys are all managed in the Kimi API open platform.

The API request domains remain unchanged: https://api.moonshot.cn for the China site and https://api.moonshot.ai for the international site. A China-site key can only be used with the China-site domain, and the same applies to the international site. If base_url is not set in the code, requests may go to OpenAI or another provider, and the typical error is model_not_found. Keep "console address" and "API address" as separate facts in your notes, and migration will be much less confusing.

2. Three Compatible Protocols and Their Base URLs

  • OpenAI Chat Completions: Base URL https://api.moonshot.cn/v1, path /chat/completions.
  • OpenAI Responses: the same Base URL, path /responses.
  • Anthropic Messages: Base URL https://api.moonshot.cn/anthropic, path /v1/messages.
  • Model list: GET https://api.moonshot.cn/v1/models.

For the international site, replace the domain with api.moonshot.ai; the paths stay the same. For the OpenAI SDK, set base_url only up to /v1, because the SDK appends the endpoint path itself; with curl, write the full path. The Anthropic entry does not carry a /v1 suffix, which differs from the OpenAI entry. The official documentation requires OpenAI SDK 1.0.0 or later, and Python 3.8+ or Node.js 18+.

3. Choosing from the Current Model Family

Model name Context Suitable tasks Notes
kimi-k3 1M Complex reasoning, long documents, agents, knowledge work reasoning_effort defaults to max
kimi-k2.7-code 256K Code generation, repository Q&A, coding agents Thinking is usually on; reasoning_effort is not supported
kimi-k2.7-code-highspeed 256K Low-latency completion, interactive coding High-speed version of the same model, faster output
kimi-k2.6 256K General chat, extraction, multimodal Supports thinking and non-thinking modes

If you are unsure, start with kimi-k3. For simple classification or fixed-format extraction, kimi-k2.6 is often a better fit; for coding tasks, consider the K2.7 Code series.

The easiest parameter trap is sampling. Current models have fixed temperatures: 1.0 for K3 and K2.7 Code, and for K2.6, 1.0 in thinking mode and 0.6 in non-thinking mode. Do not explicitly pass temperature; a non-fixed value returns an error. top_p is also fixed at 0.95, so do not adjust it yourself.

4. First Call with curl

export MOONSHOT_API_KEY="your-key"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Reply only with: integration OK"}
    ],
    "max_completion_tokens": 64
  }'

If it returns 200 with the expected content, the key, site, model name, and path are all correct. If it returns 401, first check whether the key matches the site; for 404, check the model name, /v1, and whether the model has been retired; for 400, look at whether the error message mentions the context or output limit. Some integrations have extra requirements for model names; Claude Code, for example, may need kimi-k3[1m]. Follow the documentation for that integration.

5. Python SDK and Streaming Output

import os
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Explain in three points which teams an API gateway suits"}],
    max_completion_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\nUsage:", chunk.usage)

A streaming response is SSE: each line starts with data: and the stream ends with data: [DONE]. With include_usage enabled, one extra block arrives before the end, with an empty choices array and only usage populated. If the connection drops, that block may never arrive, so production systems should keep their own usage accounting on the server side.

For multi-turn conversations and tool calling, pay attention to reasoning content. K3 places its reasoning in reasoning_content, and K2.x models have a similar field; when you send assistant messages back, include it as-is. K3 controls reasoning intensity with the top-level reasoning_effort; for K2.x, the thinking parameter must be passed through extra_body. Do not send both at once.

6. Migrating from moonshot-v1

The old models are retired, and continued calls return model_not_found. The current replacement relationships are below; the official model list is authoritative.

Old model Suggested replacement Migration note
moonshot-v1-8k/32k/128k/auto kimi-k2.6 or kimi-k3 No longer distinguished by 8K/32K/128K naming
moonshot-v1-*-vision-preview kimi-k3 or kimi-k2.6 Use image_url content blocks for images
kimi-k2 series kimi-k3 Retired on 2026-05-25
kimi-k2.5 kimi-k3 Retired on 2026-08-31
kimi-latest kimi-k3 Retired on 2026-01-28

Migration steps:

  1. Search code and configuration globally for old model names and base_url, and build a replacement list.
  2. Change base_url and confirm the China or international site; when crossing sites, replace the key as well.
  3. Replace model names, defaulting to kimi-k3; cost-sensitive short tasks can evaluate kimi-k2.6.
  4. Change max_tokens to max_completion_tokens. K3 defaults to 131072, with an output limit of 1048576 minus the input length; the K2 series caps at roughly 256K minus the input length.
  5. Remove custom temperature and top_p, and use the model's fixed values.
  6. Convert old thinking settings to K3's reasoning_effort; for K2.x, pass thinking through extra_body.
  7. Convert multimodal content to text, image_url, and video_url content blocks.
  8. Add stream_options={"include_usage": True} to streaming requests.
  9. Run a regression with the same set of real tasks, record quality, latency, finish_reason, and usage, then roll out gradually with a rollback switch.

Do not switch everything at once. Test the environment first, then low-risk business, and finally core paths; every step must be reversible.

7. Pre-Launch Verification Checklist

  • Call GET /v1/models with the same key and confirm the target model appears in the returned list.
  • Send one minimal non-streaming request and confirm a 200 with correct content.
  • Send one streaming request and confirm incremental content and the final usage block arrive.
  • Check finish_reason: stop means a normal finish, and length means the output limit was reached.
  • Compare quality, latency, and token consumption before and after migration using a fixed evaluation set.
  • Verify 429 backoff, timeouts, and retry limits, and confirm the SDK's automatic retries do not multiply concurrency.
  • Log request time, model name, status code, and usage for troubleshooting and reconciliation.

8. Common Error Reference

  • 401 invalid_authentication_error: the key is invalid, deleted, or mixed between China and international sites. Open-platform keys and Kimi Code keys are also not interchangeable.
  • 403 permission_denied_error: the IP allowlist does not include the current egress IP, or project permissions are insufficient.
  • 404 model_not_found: base_url does not point to Moonshot, the model name is wrong, a retired model was called, or the path is missing /v1.
  • 400 invalid_request_error: input plus output limit exceeds the context, or the request passes a parameter the model does not support, such as a custom temperature.
  • 400 content_filter: input or output triggered the content safety policy; adjust the prompt or material.
  • 429: engine_overloaded_error means the server is busy; rate_limit_reached_error means an organization rate limit; exceeded_current_quota_error usually means insufficient balance.
  • 504 or connection timeout: a long non-streaming request waited too long; use streaming for long-form generation and agent tasks where possible.

The OpenAI SDK retries failed requests twice by default, so one call can produce three requests. When a low-quota account hits 429, reduce retries and concurrency first, then investigate quota.

FAQ

Can I still use moonshot-v1?

No. The entire moonshot-v1 series was retired on August 31, 2026, and calls return model_not_found. Migrate to kimi-k3 or kimi-k2.6.

How far should the Base URL go?

For the OpenAI SDK, use https://api.moonshot.cn/v1 without /chat/completions; for curl, write the full /v1/chat/completions; for the Anthropic SDK, use https://api.moonshot.cn/anthropic.

Why does passing temperature return an error?

Current models have fixed temperatures: 1.0 for K3 and K2.7 Code, and a value fixed by the thinking mode for K2.6. Do not pass a custom value; top_p is also fixed at 0.95.

Can a China-site key call the international site?

No. Accounts, balances, and keys are isolated by region, and mixing them usually returns 401. When switching sites, change the key, Base URL, and model name together.

Why is usage missing after a streaming response ends?

You must explicitly set stream_options={"include_usage": True}. Even then, a dropped connection may prevent the final block from arriving, so production systems should count usage separately on the server.

Next Steps

Create a test key in the ZSQH AI Gateway, run one real task each with kimi-k3 and kimi-k2.6, confirm the path works, and then connect production. Available models and billing methods follow the model pricing page.

Related reading: