MiniMax Prompt Caching: Automatic vs Explicit Cache Control

Last verified: July 18, 2026.

Verification scope: We reviewed MiniMax’s official documentation, request schemas, usage fields, endpoint syntax, and model-support tables. We did not execute the examples against a live account because no MiniMax API credentials were available. Run them in a non-production project, inspect the returned usage object, and confirm the model and price shown in your MiniMax console before relying on the results.

MiniMax prompt caching can reduce repeated input processing when requests share a long, identical prefix. There are two separate mechanisms: automatic caching, which requires no cache marker, and explicit cache control in the Anthropic-compatible interface. They differ in API format, expiry behavior, write billing, supported models, and the amount of control given to the developer.

This guide explains both mechanisms without treating them as interchangeable. For general authentication, endpoints, and key types, begin with our MiniMax API guide. See the MiniMax pricing guide before estimating production spend.

Independent website notice: MiniMax-AI.chat is an independent website. It is not owned, operated, sponsored, endorsed by, or affiliated with MiniMax. MiniMax names, model names, logos, and related trademarks belong to their respective owners.

The short answer

• Automatic caching: send ordinary repeated requests through a supported interface. MiniMax identifies a matching prefix automatically. The input must contain at least 512 tokens for caching to apply.
• Explicit caching: use the Anthropic-compatible API and add cache_control: {"type": "ephemeral"} at selected content boundaries. The cache lifetime is five minutes and a hit refreshes that lifetime.
• Prefix order: MiniMax constructs the prefix as tools, then system content, then messages. An earlier change can prevent later content from matching.
• Do not assume M3 supports explicit caching: MiniMax’s official comparison lists MiniMax-M3 for automatic caching, but its explicit-caching support table and comparison do not list M3. Use a model explicitly shown by the official explicit-caching documentation, or obtain confirmation from MiniMax before deployment.

Automatic and explicit caching compared

Question	Automatic caching	Explicit cache control
How is it enabled?	No cache marker; repeat an eligible prefix	Add cache_control blocks
API format	Documented with OpenAI- and Anthropic-compatible examples	Anthropic-compatible API
Minimum input	512 input tokens	No minimum is stated on the explicit-caching page
Expiry	Adjusted automatically according to system load	Five minutes; a hit refreshes the lifetime
Write charge	The official comparison says no additional cache-write charge	First cache writes have a separate charge
Developer control	Low	Up to four active cache breakpoints
Model caveat	The comparison includes M3 and several M2 families	The published list includes M2.7, M2.5, M2.1, and M2 families, but not M3

Model availability and prices can change independently of this article. Treat the official support table and your account console as the authority. Our MiniMax M3 guide covers the model itself; it does not override the explicit-cache compatibility list.

How automatic MiniMax prompt caching works

Automatic caching is passive. The first eligible request establishes reusable data; a later request can receive a cache hit when its prefix is identical. MiniMax says the prefix is assembled in this order: tool list → system prompts → user messages. Put stable material first and request-specific material last.

For example, an application may send a fixed tool schema, a long policy prompt, a reference handbook, and then a different question. If the tool schema or policy changes, that change occurs early in the prefix and may reduce the matching portion. Reordering JSON objects, altering whitespace inside long text, changing a tool description, or inserting a variable timestamp can also make a supposedly stable prefix different.

Node.js example: verify an automatic cache hit

Install the OpenAI SDK with npm install openai. Store the API key and the long reusable text in server-side environment variables. The static prefix must be long enough to satisfy the 512-token rule; character count is not a reliable token count.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MINIMAX_API_KEY,
  baseURL: "https://api.minimax.io/v1",
});

const staticContext = process.env.MINIMAX_STATIC_CONTEXT;
if (!staticContext) {
  throw new Error("MINIMAX_STATIC_CONTEXT is required");
}

async function ask(question) {
  const response = await client.chat.completions.create({
    model: "MiniMax-M3",
    messages: [
      {
        role: "system",
        content: "Answer only from the supplied reference. State when the reference is insufficient.",
      },
      { role: "user", content: `REFERENCE\n${staticContext}` },
      { role: "user", content: question },
    ],
    // MiniMax extension: return thinking separately from visible text.
    reasoning_split: true,
  });

  const usage = response.usage ?? {};
  console.log({
    promptTokens: usage.prompt_tokens,
    cachedTokens: usage.prompt_tokens_details?.cached_tokens ?? 0,
  });
  return response.choices[0].message.content;
}

await ask("Summarize section one in five bullets.");
await ask("List the exceptions described in section two.");

The first request may show zero cached tokens because it is establishing the reusable prefix. The second request should preserve the same first messages and change only the final question. Check usage.prompt_tokens_details.cached_tokens; do not infer a hit only from lower latency. If the SDK version does not expose the nested field as a typed property, log the serialized usage object and inspect the raw response.

How explicit cache control works

Explicit caching gives you cache breakpoints. A breakpoint marks the end of a cumulative prefix: everything before that block participates in the cache key. MiniMax checks for the longest matching prefix. Its documented hierarchy is tools, system, and messages, so a breakpoint later in the request includes the stable blocks that precede it.

The cache lasts five minutes. A successful read refreshes that lifetime without another refresh fee, according to the official guide. Each request can contain up to four effective cache_control markers. If more than four are supplied, MiniMax says only the most recent four, counted from the end, are used.

For each explicit breakpoint, the matcher looks back through as many as 20 content blocks. A long prompt with more blocks may need additional, deliberately placed breakpoints. Adding markers everywhere is not a solution: it can exceed the four-marker limit and makes the request harder to reason about.

Python example: cache a stable system reference

This example uses MiniMax-M2.7 because that model is shown in the official explicit-caching documentation. Confirm access and pricing in your account before use. Install the SDK with pip install anthropic.

import os
from anthropic import Anthropic

api_key = os.environ["MINIMAX_API_KEY"]
reference = os.environ["MINIMAX_STATIC_CONTEXT"]

client = Anthropic(
    api_key=api_key,
    base_url="https://api.minimax.io/anthropic",
)

def ask(question: str):
    response = client.messages.create(
        model="MiniMax-M2.7",
        max_tokens=1200,
        system=[
            {
                "type": "text",
                "text": "Answer from the supplied reference and identify missing evidence.",
            },
            {
                "type": "text",
                "text": reference,
                "cache_control": {"type": "ephemeral"},
            },
        ],
        messages=[{"role": "user", "content": question}],
    )
    print({
        "input_tokens": response.usage.input_tokens,
        "cache_created": response.usage.cache_creation_input_tokens,
        "cache_read": response.usage.cache_read_input_tokens,
    })
    return response

first = ask("Summarize the approval process.")
second = ask("Which exceptions require escalation?")

On a cache creation, expect cache_creation_input_tokens to carry the cached prefix and cache_read_input_tokens to be zero. On a matching read within the lifetime, the relationship should reverse. input_tokens covers uncached input after the breakpoint; total input for cost and rate-limit analysis includes uncached, cache-created, and cache-read tokens.

What can be placed behind an explicit breakpoint?

• Tool definitions in the tools array.
• Text blocks in the system array.
• User and assistant text content blocks in messages.
• Tool-use and tool-result blocks in a conversation history.

Place a marker on the final stable tool definition to cache the preceding tool list as one prefix. For a long reference, place it on the final stable system block. In an ongoing conversation, a marker near the end can create an incremental cache, but the full conversational state still needs to be valid. Caching does not replace the message-history rules described in our MiniMax function-calling guide.

Pricing and measurement

Do not calculate savings from total input alone. Automatic caching distinguishes ordinary input, cache-hit input, and output. Explicit caching distinguishes ordinary input, cache creation, cache reads, and output. Multiply each token class by the corresponding rate for the selected model, then sum the results:

request_cost =
  uncached_input_tokens × input_rate
  + cache_read_tokens × cache_read_rate
  + cache_creation_tokens × cache_write_rate
  + output_tokens × output_rate

For automatic caching, use zero for a separate write rate when the pricing rules applicable to your model say writes have no extra charge. For explicit caching, use the published write rate. MiniMax also states that M3’s long-context pricing applies when input exceeds 512,000 tokens and that cache-hit tokens count toward that threshold. Recheck the official pricing page rather than copying an old rate into application code.

A reliable cache test

1. Create a non-production test with a stable prefix that comfortably exceeds the documented minimum for automatic caching.
2. Send request A and save its model ID, request ID, latency, full usage object, and a cryptographic hash of the intended static prefix.
3. Send request B soon afterward with byte-identical tools and system/reference blocks. Change only the final question.
4. Confirm the cache-read field is greater than zero. A fast response without cache-read tokens is not proof.
5. Change one early static block and send request C. Record how the cached-token count changes.
6. For explicit caching, repeat the test after the five-minute lifetime has elapsed and confirm a new cache creation appears.
7. Calculate observed cost by token class and compare it with an uncached baseline across several representative requests.

Common causes of a cache miss

• The prefix is too short: automatic caching requires at least 512 input tokens.
• Dynamic data appears early: timestamps, request IDs, user names, or retrieved snippets placed in the system prompt can break a large portion of the prefix.
• Tool schemas drift: changing a description, property order, enum, or tool order affects the tools-first prefix.
• Content was normalized differently: whitespace, line endings, serialization, and injected templates must remain identical in the reusable section.
• The explicit cache expired: its documented lifetime is five minutes and is refreshed by a hit.
• The matching block is outside the lookback: explicit matching checks as many as 20 blocks before a breakpoint.
• Too many breakpoints were supplied: only four are effective.
• The model is unsupported: M3 is absent from the published explicit-cache model list.

If the API rejects the request, separate a transport or account error from a genuine cache miss. Our MiniMax API error guide explains authentication, rate-limit, timeout, balance, and token-limit failures.

Security and operational boundaries

A cache marker is a performance and billing control, not an authorization mechanism. Do not place secrets, unrestricted personal data, or material your application is not permitted to send in a prompt merely because it may be cached. Keep the API key on the server, apply access controls before assembling context, minimize logs, and follow the data-handling terms governing your MiniMax account.

Cache behavior should also be observable. Log token counts, model identifiers, request IDs, prefix versions, and latency without logging sensitive prompt bodies. Alert on a sustained drop in cache-hit ratio, but do not treat every miss as an incident; eviction and load-adjusted automatic expiry are part of the documented behavior.

Which mode should you choose?

Choose automatic caching when you use M3, want minimal integration work, and can keep a long prefix stable. Choose explicit caching when your selected model is present in MiniMax’s explicit support list and your application benefits from intentional breakpoints, measurable cache creation, and a defined five-minute lifetime. If M3 plus explicit markers is a hard requirement, pause implementation until MiniMax adds M3 to the explicit support table or confirms support through an authoritative account channel.

Frequently asked questions

Does MiniMax automatic caching require a request parameter?

No. MiniMax describes it as passive caching that identifies repeated context without changing the API call method. The request still needs an eligible, repeated prefix and at least 512 input tokens.

Is MiniMax-M3 supported by explicit cache control?

Do not assume so. The official automatic-versus-explicit comparison lists M3 under automatic caching but omits it from explicit caching. The detailed explicit page also demonstrates M2-family models. Verify support before sending M3 with cache_control.

How long does an explicit cache last?

Five minutes. A cache hit refreshes that lifetime according to MiniMax’s guide.

Why did latency fall while cached tokens stayed at zero?

Network conditions, service load, and output length also affect latency. Use the response’s cache usage fields as evidence of a hit.

Can caching bypass a context limit or rate limit?

No. Cached tokens still contribute to total input accounting, and MiniMax explicitly says cache reads matter for rate limits and M3’s long-context pricing threshold.

Official sources

• MiniMax Prompt Caching documentation
• MiniMax Explicit Prompt Caching documentation
• MiniMax pay-as-you-go pricing