Last verified: November 9, 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. 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. On the current text models, MiniMax-M3.1-Flash and MiniMax-M3, caching is automatic and needs no cache marker. Explicit cache control, the cache_control markers of the Anthropic-compatible interface, was documented only for M2-series models, and MiniMax’s API reference marks it as not supported by M3.1 Flash or M3.
This guide covers automatic caching on M3.1 Flash and M3, and what changes for code written around M2-era cache markers. For general authentication, endpoints, and key types, begin with our MiniMax API guide. See the MiniMax pricing guide before estimating production spend.
The short answer
- Automatic caching: send ordinary repeated requests to MiniMax-M3.1-Flash or MiniMax-M3 through the OpenAI- or Anthropic-compatible API. MiniMax identifies a matching prefix automatically. The input must contain at least 512 tokens for caching to apply.
- Explicit caching: the Anthropic-compatible
cache_control: {"type": "ephemeral"}markers were documented for M2-series models only. MiniMax’s API reference markscache_controlas not supported by MiniMax-M3 or MiniMax-M3.1-Flash, so remove the markers when you move to a current model. - Prefix order: MiniMax constructs the prefix as tools, then system content, then messages. An earlier change can prevent later content from matching.
- Cache-hit price: on pay-as-you-go, cache hits cost $0.015 per 1M tokens on MiniMax-M3.1-Flash. On MiniMax-M3 (Standard tier) they cost $0.06 per 1M tokens for requests up to 512K input tokens and $0.12 above that. MiniMax lists no cache-write price for either model.
Automatic and explicit caching compared
| Question | Automatic caching | Explicit cache control (M2 series) |
|---|---|---|
| How is it enabled? | No cache marker; repeat an eligible prefix | cache_control blocks in the request |
| API format | Documented with OpenAI- and Anthropic-compatible examples | Anthropic-compatible API |
| Minimum input | 512 input tokens | No minimum was stated on the explicit-caching page |
| Expiry | No fixed lifetime is published | Five minutes; a hit refreshed the lifetime |
| Write charge | No cache-write price is listed for M3.1 Flash or M3 | First cache writes had a separate charge |
| Developer control | Low | Up to four active cache breakpoints |
| Supported models | MiniMax-M3.1-Flash and MiniMax-M3 | Documented for the M2.7, M2.5, M2.1, and M2 families only; not supported by M3 or M3.1 Flash |
Model availability and prices can change independently of this article. Treat MiniMax’s documentation and your account console as the authority. Our MiniMax M3.1 Flash guide and MiniMax M3 guide cover the models themselves.
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.
Explicit cache control on M2-series models
Explicit caching gave M2-series requests cache breakpoints. A cache_control marker ended a cumulative prefix (tools, then system, then messages), and MiniMax matched the longest cached prefix before it. According to MiniMax’s explicit-caching guide, each cache lived for five minutes and every hit refreshed it, a request could use at most four markers, and matching looked back through up to 20 content blocks from each marker.
The feature does not extend to MiniMax-M3 or MiniMax-M3.1-Flash: the Anthropic-compatible API reference marks cache_control as not supported by either model, and MiniMax no longer publishes a separate explicit-caching page. MiniMax closed M2.5 and M2.7 to new users on October 19, 2026, and set November 18, 2026 as their retirement date. After that date, API requests to those models no longer work. The Model List shows M2.1 and M2 as retired and gives no date for them.
To move an M2-series integration that used explicit caching, remove the markers and keep the stable tools, system text, and reference material at the start of every request. Automatic caching applies to calls with 512 or more input tokens. On M Plan and Token Plan, MiniMax has routed requests that name M2.5 or M2.7 to M3.1 Flash since October 19, 2026, so plan traffic that still uses those names is already served by a model where cache_control is not supported.
Python example: move an explicit-caching request to M3.1 Flash
This example is a typical M2-era explicit-caching request moved to MiniMax-M3.1-Flash: the system blocks stay the same, and the cache_control marker on the reference block is gone. The low effort level keeps thinking short for a cache test; thinking counts toward max_tokens, so leave room for it. 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-M3.1-Flash",
output_config={"effort": "low"},
max_tokens=4096,
system=[
{
"type": "text",
"text": "Answer from the supplied reference and identify missing evidence.",
},
{
"type": "text",
"text": reference,
},
],
messages=[{"role": "user", "content": question}],
)
print({
"input_tokens": response.usage.input_tokens,
"cache_read": response.usage.cache_read_input_tokens,
})
return response
first = ask("Summarize the approval process.")
second = ask("Which exceptions require escalation?")The first call may report zero cache_read_input_tokens because it establishes the cache. On the second call, that field should account for most of the shared system blocks, including the reference. On the Anthropic-compatible API, input_tokens counts only new, uncached input, so total input is the sum of the two fields. The OpenAI-compatible API reports it the other way around: prompt_tokens is the total and prompt_tokens_details.cached_tokens is the cached part.
What can be part of the cached prefix?
- Tool definitions in the
toolsarray. - Text blocks in the
systemarray. - User and assistant text content blocks in
messages. - Tool-use and tool-result blocks in a conversation history.
Each of these can be reused as long as it sits before the content that changes. Keep the tool list, the system blocks, and the stable opening messages identical from request to request; MiniMax builds the prefix in that order. In an ongoing conversation, earlier turns that are resent unchanged can match too, 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. MiniMax bills a cached request in three parts: new input at the input rate, cache hits at the cache-read rate, and output at the output rate. 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
+ output_tokens × output_rate ) ÷ 1,000,000Rates are in US dollars per 1M tokens, which is why the sum is divided by 1,000,000. MiniMax lists no cache-write rate for MiniMax-M3.1-Flash or MiniMax-M3, so the formula has no write term. MiniMax’s pay-as-you-go rates on the verification date:
| Model | Input (per 1M tokens) | Cache read (per 1M tokens) | Output (per 1M tokens) |
|---|---|---|---|
| MiniMax-M3.1-Flash | $0.15 | $0.015 | $0.60 |
| MiniMax-M3, up to 512K input tokens | $0.30 | $0.06 | $1.20 |
| MiniMax-M3, above 512K input tokens | $0.60 | $0.12 | $2.40 |
M3.1 Flash has one rate at every input length. The M3 rates are for the Standard tier; Priority, enabled with service_tier: "priority", costs 1.5 times as much. For example, an M3.1 Flash request with 1,200 input tokens, 800 of them cache hits, and 300 output tokens costs (400 × 0.15 + 800 × 0.015 + 300 × 0.60) ÷ 1,000,000 = $0.000252.
On M3, the higher rates apply once a request’s input exceeds 512K tokens. The September 2026 version of MiniMax’s caching page said cache-hit tokens count toward that threshold; the November 2026 version does not mention it. Until MiniMax says otherwise, include cached tokens when you check whether an M3 request crosses 512K. Recheck the official pricing page rather than copying an old rate into application code.
A reliable cache test
- Create a non-production test with a stable prefix that comfortably exceeds the documented minimum for automatic caching.
- Send request A and save its model ID, request ID, latency, full usage object, and a cryptographic hash of the intended static prefix.
- Send request B soon afterward with byte-identical tools and system/reference blocks. Change only the final question.
- Confirm the cache-read field is greater than zero. A fast response without cache-read tokens is not proof.
- Change one early static block and send request C. Record how the cached-token count changes.
- Repeat request B after longer pauses to see how long hits last for your traffic; MiniMax publishes no fixed cache lifetime.
- 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 cache entry expired: MiniMax publishes no fixed lifetime for automatic caching, so a long gap between requests can end in a miss.
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
Prompt caching is a performance and billing feature, 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; MiniMax does not promise a fixed cache lifetime.
Which mode should you choose?
On the current models there is one mode: MiniMax-M3.1-Flash and MiniMax-M3 cache automatically, and neither supports cache_control. The choice that matters is the model. M3.1 Flash has the lowest cache-read rate and one price at every input length. M3’s rates double above 512K input tokens, and only M3 offers the Priority tier. If a design depended on explicit breakpoints, restructure the requests so the stable content comes first.
Frequently asked questions
Does MiniMax automatic caching require a request parameter?
No. MiniMax says it identifies repeated context automatically, 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?
No. MiniMax’s Anthropic-compatible API reference marks cache_control as not supported by MiniMax-M3 or MiniMax-M3.1-Flash. Both models cache automatically, so leave the markers out and put the stable content at the start of the request.
How long does a MiniMax prompt cache last?
MiniMax publishes no fixed lifetime for automatic caching on MiniMax-M3.1-Flash and MiniMax-M3, so measure hit rates on your own traffic. The five-minute lifetime, refreshed by each hit, belonged to explicit caching on M2-series models.
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. A cached prefix is still part of the prompt, so the whole request must fit the model’s context window. MiniMax’s rate-limit page counts tokens per minute as input plus output and makes no exception for cache hits, so plan capacity as if cached tokens count.