The Moonshot API is the interface of the Moonshot AI open platform. The platform changed considerably in 2026: the developer console moved to platform.kimi.com, the main model line became the Kimi K3 and K2.7 series, and the old moonshot-v1 series was retired on August 31, 2026. Many teams that report "access from China does not work" actually have a mismatch in the entry point, model name, or account region rather than a network problem.

This article compares three routes — direct connection, a self-built proxy, and a domestic AI gateway — and adds acceptance methods for networking, payment and invoicing, rate limits, and failover. Models and prices follow the model pricing page.

Note: Moonshot, Kimi, and Moonshot AI are trademarks or registered trademarks of Beijing Moonshot AI Technology Co., Ltd. This article is a technical discussion and has no affiliation with the trademark owner; endpoints, models, and billing rules follow the official documentation.

1. First Confirm Which Platform You Are Accessing

The Moonshot API now has three layers that are easy to confuse, and getting any one of them wrong produces an error:

  • Brand layer: Moonshot AI is the company name, and Kimi is the model and product name. They are not two independent services.
  • Platform layer: the China site is platform.kimi.com, and the international site is platform.kimi.ai. Accounts, balances, and keys are fully independent between the two sites, and mixing them returns 401.
  • Interface layer: the China site commonly uses https://api.moonshot.cn/v1; the international site uses a different domain, per the official documentation.

Open-platform keys, Kimi client memberships, and credentials for products such as Kimi Code are not interchangeable. Using a client-product key against the open platform also fails authentication. Confirm which platform you registered on and which product line the key belongs to before discussing network optimization.

2. Three Routes in One Table

Dimension Official direct Self-built proxy Domestic AI gateway
Entry point Official addresses such as api.moonshot.cn Reverse proxy on your own domain Gateway's unified OpenAI-compatible address
Account and billing Official account, RMB top-up Official bill plus server cost Gateway account, unified RMB bill
Model scope Moonshot/Kimi only Depends on proxy configuration Multiple model families, subject to activation
Operations responsibility Vendor plus local network Entirely yours Shared between provider and local team
Suitable teams Single model, stable access, able to handle rate limits Have operations capacity and need a unified egress and audit Multiple models, need invoices, want less operations work

No single route fits everyone. A useful order for deciding is: whether the business can tolerate interruptions, whether multiple models and unified invoicing are needed, and whether anyone on the team maintains retries and monitoring. If all three are simple, direct connection is enough; if any one becomes complex, consider adding a layer.

3. Networking: The Four Things Worth Checking

Accessing the Moonshot API from mainland China usually does not require additional network tools, but the following four problems are often misdiagnosed as "the network is down":

  1. Region and key mismatch: a China-site key paired with an international-site address, or the reverse, returns 401 directly. This is not a DNS problem.
  2. Corporate proxy and TLS interception: corporate proxies that rewrite certificates or resolve DNS incorrectly appear as certificate errors, timeouts, or 499.
  3. Long-request timeouts: if a non-streaming request goes too long without a server response, a gateway may return 504; the official documentation mentions a 900-second scenario. Long-form generation should default to streaming.
  4. International-site IP allowlist: the international site may restrict calling IPs, and an address not added to the organization allowlist returns 403. Changing networks will not help with this error; configure it in the console.

Production should also enable connection reuse to avoid a new handshake on every request. Streaming requests need idle timeouts and heartbeats so an intermediary proxy does not cut a connection that carries no data for a long time.

4. Payment and Invoicing: Where Enterprise Rollouts Often Stall

A working technical integration does not mean the service can go live; procurement and finance are often the bottleneck. According to the official 2026 guidance, enterprise verification requires a company name, a corporate bank account matching that name, and a Unified Social Credit Code, and the platform deposits a random amount to verify account ownership. A personal account can be upgraded to an enterprise account, but an enterprise account cannot change its type back.

For top-up, individuals can use WeChat or Alipay; enterprises can top up online or by corporate transfer. A corporate transfer must come from the verified entity's account, usually takes one to five business days to arrive, and then about ten minutes to post. Invoices can be requested online, based on consumed amount or top-up amount, and the invoicing entity is Beijing Moonshot AI, with technical service fees as the item. An enterprise account can only use the verified entity as the invoice title; only a personal account can choose an individual or company title.

If the company requires a contract, payment terms, or a special VAT invoice, confirm through the sales channel first rather than discovering after top-up that the process does not match. Gateway payment and invoicing rules differ, so confirm them in writing before signing as well.

5. Rate Limits: 429 Is Not One Error

Moonshot assigns rate-limit tiers by cumulative top-up amount; higher tiers allow wider concurrency, RPM, TPM, and TPD. Coupons are usually excluded from the cumulative total, so "adding a coupon" does not necessarily raise the tier. Web-search QPS is a separate quota, calculated independently from the chat endpoint's RPM and TPM.

The same 429 requires completely different handling:

  • engine_overloaded_error: the server is overloaded; back off and retry according to Retry-After. Topping up or upgrading the tier will not help.
  • rate_limit_reached_error: organization concurrency, RPM, TPM, or TPD has been exceeded; slow down, queue, or wait for the reset.
  • exceeded_current_quota_error: arrears or insufficient quota; do not retry, resolve the balance first.

The platform may also apply risk-control rate limits to abnormal accounts, and the official documentation states that such limits may not be removable once triggered. Projects can also set a daily budget; after the cap, all requests in that project are rejected, with a possible lag of about ten minutes due to billing delay. Enable low-balance SMS alerts as well, so you do not discover arrears only when a 429 appears.

6. Failover: Only Meaningful for Transient Errors

Failover does not mean "switch routes for every error." Insufficient balance, a wrong key, parameter errors, and content-safety errors cannot be solved by changing channels, and switching only amplifies bills and troubleshooting difficulty. Here is a minimal structure:

import os
from openai import OpenAI

clients = [
    OpenAI(api_key=os.environ["PRIMARY_KEY"],
           base_url=os.environ["PRIMARY_BASE"], max_retries=0),
    OpenAI(api_key=os.environ["BACKUP_KEY"],
           base_url=os.environ["BACKUP_BASE"], max_retries=0),
]

def ask(prompt: str) -> str:
    last_error = None
    for client in clients:
        try:
            resp = client.chat.completions.create(
                model=os.environ["MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_completion_tokens=512,
                stream=False,
            )
            return resp.choices[0].message.content
        except Exception as exc:  # In production, branch on error.type
            last_error = exc
            if "quota" in str(exc).lower() or "content_filter" in str(exc).lower():
                raise
    raise RuntimeError("Primary and backup channels are both unavailable") from last_error

Note that China-site and international-site accounts are independent, so "geographic disaster recovery" cannot be achieved by changing only the Base URL; the backup channel must be registered, funded, and verified separately in advance. After switching, record request_id, model name, usage, and latency; otherwise you cannot tell whether the backup channel is actually working.

7. Pre-Launch Acceptance Checklist

  1. Send a minimal request with a currently available model, such as kimi-k3 or kimi-k2.6, and confirm a 200 response.
  2. Verify the Chat Completions, Responses, and Anthropic Messages formats separately, and confirm that every protocol the project uses works.
  3. Check that model, usage, and request_id are present in the response and can be logged.
  4. Test streaming with a long output and confirm chunk-by-chunk delivery, a complete ending, and no buffering by an intermediary proxy.
  5. Deliberately trigger 401, 404, and 429, and check that the client distinguishes the error types correctly.
  6. Set connection and read timeouts, enable Keep-Alive, and configure a project daily budget and balance alerts.
  7. Observe p50 and p95 latency plus 429 and 5xx ratios for a full week, not just a single load test.
  8. Walk through the corporate transfer and invoicing process and confirm the contract, invoice, and refund rules.
  9. Keep a rollback-capable direct channel and document the switching conditions.

Do not move core business until acceptance passes. A gateway adds a hop and may slightly increase latency; its value lies in a unified entry point, failover, billing, and key isolation, not in "acceleration."

FAQ

Are the Moonshot API and the Kimi web app the same thing?

No. The web app is a user-facing product, while the Moonshot API is an open-platform interface for developers. Their account systems, billing methods, and keys are different.

Does direct access from mainland China need extra network tools?

Usually not. Moonshot is a Chinese vendor, and the China-site endpoints can be accessed directly from mainland China. What actually happens more often is a region, key, model-name, or proxy configuration error.

Can old moonshot-v1 code still be used?

The moonshot-v1 series was retired on August 31, 2026, and continued calls return 404. Migrate to kimi-k3, kimi-k2.7, or kimi-k2.6 according to the official model list, and recheck the parameters.

Must enterprise payments use corporate bank transfer?

It is not the only option. After enterprise verification, you can choose online top-up via WeChat or Alipay, or corporate transfer; corporate transfer arrives more slowly and suits teams with a finance workflow.

What if a 429 never recovers?

Check error.type first. If quota is insufficient, top up; if concurrency or TPD is exceeded, slow down and wait for the reset; if the server is overloaded, back off according to Retry-After. If it still does not recover, keep the request_id and contact platform support.

Next Steps

If you use several model families, need unified invoicing, or want a backup channel, create a test key in the ZSQH AI Gateway and compare latency, error rates, and bills between direct access and the gateway using the same request set before deciding which path production should take. Specific models and billing rules follow the model pricing page.

Related reading: