The Moonshot API refers to the model endpoints provided by the Moonshot AI open platform, the developer platform behind Kimi. It bills by token usage and has no subscription plan. Teams tend to make two budgeting mistakes: they keep calling the retired moonshot-v1 models, or they blend input, cache writes, output, and retries into a single average unit price. This article breaks down the billing structure according to public documentation as of October 2026. Actual prices follow the model pricing page and the official documentation.

Note: Moonshot and Kimi are trademarks of their respective owners. This article is a technical explanation only and does not imply any affiliation with or agency for the trademark owners. Model lists, context lengths, and billing rules may change; recheck the official pages before purchasing.

1. Separate "Current Models" from "Retired Models"

As of October 2026, the main models listed in the open-platform documentation are kimi-k3, kimi-k2.6, kimi-k2.7-code, and kimi-k2.7-code-highspeed. The old moonshot-v1 series has been retired: moonshot-v1-8k, -32k, -128k, -auto, and their vision preview versions were all taken offline on August 31, 2026, and kimi-k2.5 was retired the same day. The earlier kimi-k2 preview versions, kimi-latest, and others have also stopped serving.

Model Context Billing structure Status and notes
kimi-k3 1,048,576 Input, cache hit, cache write, output Current flagship; the recommended migration target
kimi-k2.6 262,144 Input, cache hit, output General and multimodal, common for cost-sensitive work
kimi-k2.7-code 262,144 Input, cache hit, output Code generation, repository Q&A, and agents
kimi-k2.7-code-highspeed 262,144 Input, cache hit, output Low-latency coding tasks
moonshot-v1-8k/32k/128k By model name Old length-based tiers Retired on 2026-08-31

Model names in old tutorials cannot be copied directly. The "8k" in moonshot-v1-8k was itself a context tier, so a failed call is not a key problem but a model that no longer exists. When migrating, change the model name first, then recheck the context window and billing items; do not perform a simple string replacement.

2. Billing Units: One Request Splits into Four Parts

A current bill usually consists of four token categories: input that misses the cache, input that hits the cache, cache writes, and output. K3 prices cache writes separately for 5-minute and 1-hour TTL tiers; the K2 series pricing page does not list cache writes as a separate line item. Written as a formula, one request looks like this:

Cost per request =
  cache-miss input tokens × miss rate
+ cache-hit input tokens × hit rate
+ cache-write tokens × rate for the TTL tier (K3 only)
+ output tokens × output rate

The official documentation offers a useful conversion: for standard Chinese text, roughly 1.5 to 2 Chinese characters correspond to one token. Multiplying character counts directly by a unit price underestimates input volume. For formal estimates, use the POST /v1/tokenizers/estimate-token-count endpoint, or read the usage object returned by the actual call.

For Chat Completions, the usage fields are usage.prompt_tokens and usage.completion_tokens, with cache details in usage.prompt_tokens_details.cached_tokens and cache_write_tokens. For the Messages API, input_tokens excludes the cached portion, so total input is the sum of input_tokens, cache_read_input_tokens, and cache_creation_input_tokens. Streaming calls must set stream_options.include_usage=true.

3. How Caching Is Billed and Why It Misses

Context caching matches by prefix, not by the whole conversation. If any part of the prefix changes, everything after that position cannot be reused. Common behaviors that break the prefix include inserting timestamps or random IDs into the system prompt, reordering tool definitions on every request, dynamically concatenating knowledge-base fragments, and switching TTL tiers. Caches are also isolated by organization and are not shared across organizations.

K3 bills cache writes when the prefix is first written, with a fixed TTL of 5 minutes or 1 hour; the tier cannot be changed midway after writing. Hits renew the cache under the original TTL at no charge and do not incur another write fee. The two cache tiers do not share data. If the tail of the prefix is smaller than a complete cache block, that part is usually treated as a miss.

Caching is not a switch that saves money simply by turning it on; it is prefix engineering. Put the system prompt, tool definitions, fixed examples, and the common part of the knowledge base first, place variables last, and then verify the hit rate with cached_tokens.

4. Long-Context Cost: The Expense Is Repeated Transmission

K3 supports a 1,048,576-token context, while the K2 series offers 262,144 tokens. K3 uses unified usage-based pricing and no longer divides by 8k, 32k, and 128k length tiers as the old moonshot-v1 did, so you cannot extrapolate K3 pricing from the old tier table.

Long context itself is not the problem; the problem is resending the same material every turn. In a 200,000-token document Q&A session with ten consecutive follow-ups that each include the full text, input cost accumulates quickly with every turn; tool logs, web page bodies, and code results also remain in history and continue to be billed. A more common approach is to retrieve relevant passages first and then let the model read them, use rolling summaries for multi-turn conversations, turn stable parts into a cached prefix, and reserve long context only for source text that must be preserved.

Long context also amplifies latency and failure rates. Long non-streaming requests are more likely to hit gateway timeouts, and retries create additional input usage. Long tasks should prefer streaming output and set a reasonable read timeout.

5. How Retries and Failed Requests Are Counted

The official error codes divide 429 into three categories: rate_limit_reached_error means the organization's concurrency, RPM, TPM, or TPD limit was reached; exceeded_current_quota_error means insufficient balance or quota; engine_overloaded_error means the server is capacity-constrained. Only balance problems can be solved by topping up; capacity overload cannot be removed directly by payment. For 500 and 503, retrying later is usually advised; for gateway timeouts on long requests, switching to streaming is better than resending the same request.

The official documentation does not promise that failed requests are free. The prudent approach is not to assume retries cost nothing: reconcile with request logs and usage, and track retry counts separately. A retry policy can be implemented in this order:

  1. Classify by error code first; do not retry arrears, parameter errors, or content moderation failures.
  2. Retry only 429 rate limits, 500, 503, and network interruptions, and only a limited number of times.
  3. Use exponential backoff with random jitter, and honor Retry-After.
  4. Set a retry cap and total time limit so retries do not occupy concurrency indefinitely.
  5. Give tool calls idempotency keys or a deduplication table to prevent duplicate orders or duplicate messages.
  6. Record request_id, model name, token usage, and retry count for reconciliation.

6. Budget Estimation: From Tokens to a Monthly Cap

Do not derive a budget backward from "price per million tokens"; derive it from real tasks. Select 20 to 50 representative tasks covering simple, medium, and complex levels, define acceptance criteria, measure input with the estimation endpoint, read usage from real calls, and compare models by "total cost to complete one acceptable task."

import os
import requests

resp = requests.post(
    "https://api.moonshot.cn/v1/tokenizers/estimate-token-count",
    headers={"Authorization": f"Bearer {os.environ['MOONSHOT_API_KEY']}"},
    json={
        "model": "kimi-k3",
        "messages": [{"role": "user", "content": "Extract this contract into JSON: ..."}],
    },
    timeout=30,
)
print(resp.json()["data"]["total_tokens"])

After estimating the input for a single call, add four more components: history messages, tool returns, the cache-miss ratio, and extra calls caused by retries. Offline batch processing can evaluate the Batch API, which the official documentation says is roughly 40% lower than synchronous calls, but it currently supports only kimi-k2.7-code and kimi-k2.6; kimi-k3 is not yet supported.

Budget control should have three layers: daily and monthly budgets per project, where the console rejects that project's requests after the cap, though enforcement may lag by about ten minutes; separation by key or member so one business line cannot consume the whole organization quota; and weekly reconciliation by model and scenario to find the fastest-growing calls. Balance alerts only guard against sudden cutoffs and do not replace budgets.

7. Cost-Reduction Order and Reconciliation Habits

Do not reverse the order of cost reduction. Handle caching and input governance first, then limit output, and only then consider switching models; otherwise you are merely making wrong answers cheaper.

  1. Fix the system prompt, tool definitions, and knowledge-base prefix, and verify cached_tokens.
  2. Use retrieval and summaries to reduce the source text sent each time, and apply rolling summaries to history.
  3. Set max_completion_tokens, request JSON or fixed fields, and reduce open-ended long outputs.
  4. Route models by task: kimi-k2.6 for general work, the K2.7 Code models for coding, and K3 only for very long material.
  5. Switch long requests to streaming to reduce retries caused by timeouts and disconnects.
  6. Send offline jobs through the Batch API and keep synchronous endpoints for real-time work.
  7. Reconcile monthly by project, model, and scenario, recording cache hit rate, retry count, and average output length separately.

A reconciliation statement should include at least: call time, project, model, input tokens, cache-hit tokens, cache-write tokens, output tokens, retry count, and request_id. Without these fields, any billing discrepancy can only be guessed at.

FAQ

Can moonshot-v1-8k still be called?

No. The entire moonshot-v1 series was retired on August 31, 2026, and the official recommendation is to migrate to kimi-k3. Migration requires more than a model-name change: recheck the context length, billing items, and output parameters as well.

Why is the cache hit not taking effect?

First check whether the prefix is broken by timestamps, random IDs, dynamic ordering, or reordered tools. Then confirm that the interval between requests does not exceed the TTL. Finally, confirm that cache writes and reads occur in the same organization and the same TTL tier. Judge by cached_tokens, not by intuition.

Is long context always more expensive?

Not necessarily, but repeatedly sending long material usually is. Cost depends on how many times the input is repeated, the cache hit rate, and output length. Use retrieval to narrow the scope first, then decide whether million-token context is needed.

Are failed requests billed?

The official documentation does not promise that failures are free. Do not assume retries cost nothing; verify with request logs and usage, and include retry counts in the per-task cost.

Where can I find the latest prices?

Use the model pricing page and the official Moonshot/Kimi documentation. Prices, model lists, and caching rules may all change, so do not rely on old screenshots.

Next Steps

Create a test key in the ZSQH AI Gateway, run a batch of real tasks with kimi-k2.6 and kimi-k3, record input, output, cache hits, and retries, and then decide on the primary model and monthly budget. Specific prices and available models follow the model pricing page.

Related reading: