Kimi K3.1 Pro context prefix caching and TTL configuration: automatic writes, hits, and usage verification

One-sentence takeaway

The Kimi API automatically reuses fixed content based on the request prefix; Kimi K3.1 Pro supports Cache Write, with a default 5m TTL or an explicit 1h TTL, but the order and exact text of the stable prefix must remain unchanged, and hits and writes must be verified through the API's usage fields.

Use cases

• Suitable tasks: Documentation Q&A, coding agents, long-running conversations, and scheduled reports that repeatedly send product documentation, codebases, tool definitions, or system prompts.

• Unsuitable tasks: Workflows where the prefix is rarely reused, the interval between requests exceeds the TTL, or the cache must be cleared manually.

• Applicable model version: kimi-k3.1-pro; the official FAQ explicitly lists it as supporting Cache Write.

• Applicable client, agent, or API: Kimi API Chat Completions and Responses; Anthropic Messages uses the corresponding top-level cache_control.

• Recommended reasoning level and parameters: For Chat Completions/Responses, omitting prompt_cache_options uses 5m; set ttl="1h" when the interval may exceed 5 minutes but remain within 1 hour.

Ready-to-use content

The official minimal Chat Completions configuration is retained below. mode currently supports only implicit, while ttl supports only 5m and 1h:

curl https://api.moonshot.ai/v1/chat/completions \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{
    "model": "kimi-k3.1-pro",
    "messages": [
      {"role": "system", "content": "You are a product documentation assistant.\n\nProduct documentation: ..."},
      {"role": "user", "content": "Which authentication methods does this product support?"}
    ],
    "prompt_cache_options": {"mode": "implicit", "ttl": "1h"}
  }'

Testing or workflow steps

1. Put the system prompt, tool definitions, reference materials, and codebase that will not change at the beginning of the request.

2. Put the user question, tool results, and task state that change each round at the end.

3. Keep the order and exact text of fixed content unchanged within the same conversation; do not put timestamps or random IDs in the prefix.

4. Omit prompt_cache_options to let Chat Completions/Responses automatically write and reuse the prefix with a 5m TTL; for longer intervals, explicitly use {"mode":"implicit","ttl":"1h"}.

5. Keep scheduled request intervals within the TTL; a hit renews the TTL at no additional charge.

6. Note that the cache is isolated by organization, 5m and 1h are two separate caches that are not shared, and the cache cannot be deleted manually.

7. If request intervals usually exceed 1 hour, do not configure caching specifically for that prefix.

8. For streaming Chat Completions, set stream_options.include_usage=true to obtain the complete read/write breakdown in the final chunk.

9. Use the response usage fields to record total input, cache read, and cache write; do not look only at total input tokens.

Original evidence and data

• The cache matches the request prefix; after any position in the prefix changes, content after that position cannot be reused.

• kimi-k3.1-pro and kimi-k3 support Cache Write; K2.7, K2.7 Highspeed, and K2.6 listed in the page FAQ do not.

• Cache Write is billed separately; hit portions are billed only as Cached Input, and a hit within the same TTL does not incur another write charge.

• The cache is stored in blocks; content smaller than one complete block cannot be written to the cache and is billed at the regular cache-miss input price.

• The TTL is locked when the first write occurs; a hit renews only the original TTL, and new content is written with the locked TTL as well. The TTL cannot be changed until the entry has fully expired.

• The official page uses kimi-k3 to show prices: Input (miss) $3.00/1M tokens, Cache Write 5m $3.00, Cache Write 1h $6.00, and Cached Input $0.30. These are the page's price examples for kimi-k3; this article does not extrapolate them to the current K3.1 Pro price.

• For a 1M-token prefix, 1h adds only a $3.00 write charge compared with 5m; the official documentation says two additional hits are enough to cover the difference. This article did not conduct price or hit testing.

• Chat Completions fields are usage.prompt_tokens, usage.prompt_tokens_details.cached_tokens, and usage.prompt_tokens_details.cache_write_tokens.

• Responses fields are usage.input_tokens, usage.input_tokens_details.cached_tokens, and usage.input_tokens_details.cache_write_tokens.

• For Messages, total input must be calculated by adding input_tokens + cache_read_input_tokens + cache_creation_input_tokens; writes can also be broken down into ephemeral_5m_input_tokens and ephemeral_1h_input_tokens.

• In Chat Completions/Responses, cache read, cache write, and uncached portions are mutually exclusive and sum to total input; in Messages, input_tokens excludes cached reads and writes.

• The console provides Caching Overview, which shows hits, misses, cache-write tokens, hit rate, and cache-write amortization multiple; billing details also provide 5min/1h write fields.

• Anthropic Messages' cache_control takes effect only at the top level; placing it inside messages content is ignored, and omitting it likewise uses 5m.

• After billing is split out, existing requests require no changes; monthly bills can show 5m/1h write details by project, organization, and API key.

• Chat Completions response headers Msh-Usage-Cache-Write-Tokens-5m and Msh-Usage-Cache-Write-Tokens-1h identify tokens written under each TTL for the current request.

• When there is no new write, the corresponding write response header is 0; the billing reconciliation formula is: input tokens = uncached tokens + hit tokens + write tokens.

Scope and limitations

• The page presents the caching mechanism and the kimi-k3.1-pro example in the same API guide, but the pricing table explicitly refers to kimi-k3; it cannot be used to infer the K3.1 Pro price.

• “Automatic writes” are conditional on the hit requirements being met; when the prefix is shorter than a complete block, the content changes, or the entry has expired, it cannot be treated as a hit.

• The cache is isolated by organization; it can be shared within the same organization but not across organizations.

• 5m and 1h are not interchangeable labels; the TTL of a written entry cannot be changed while it is valid.

• The official documentation describes configuration and billing rules; this article did not make a real API request and has no fabricated hit rate, latency, or measured price results.

• The page defines hit rate and the cache-write amortization multiple as console observation metrics; this article does not rewrite them as fixed performance commitments for K3.1 Pro.

Reproduction notes

1. Open the official Context Caching guide and confirm the title, the K3.1 Pro example, and the FAQ.

2. Using a test API key, omit prompt_cache_options, set ttl="5m", and set ttl="1h" in separate requests, keeping the fixed prefix exactly identical.

3. Record cached tokens, cache-write tokens, and uncached input from the response; enable include_usage before making a streaming request.

4. Do not treat a successful HTTP request, billing display, or the presence of configuration in code as a hit test; verify against the actual usage fields and console cache statistics separately.

5. When reproducing different TTLs, first let the original entry expire completely, then write the same prefix with the new TTL.