For qwen4-max, set prompt_cache_breakpoint: {"mode":"explicit"} on a fixed input content block and resend the same prefix within its validity period to reuse the cache deterministically. The prefix must contain at least 1,024 tokens. The default TTL is 5 minutes, and it can also be set to 1 hour.
Suitable tasks: Multi-turn conversations, long-document Q&A, agents, and other requests that repeatedly send the same long prefix
Unsuitable tasks: Requests whose prefixes are frequently rewritten, or whose cacheable portion contains fewer than 1,024 tokens
Applicable model versions: The Qwen4 series; the official example uses the released model ID qwen4-max
Applicable clients, agents, or APIs: OpenAI-compatible Chat Completions, Responses, and Anthropic Messages API; this article's example uses the OpenAI Python SDK
Recommended reasoning level and parameters: Put fixed content before variable content; choose 5m or 1h for the TTL based on the reuse interval
The example uses the Singapore QwenCloud OpenAI-compatible endpoint. First, set the API key for the corresponding region:
export DASHSCOPE_API_KEY="YOUR_QWENCLOUD_API_KEY"Install the OpenAI Python SDK:
python -m pip install openaiThe following request sets fixed reference material as the cache prefix, places the question after the breakpoint, and sets a 1-hour TTL. When sent twice in a row, only the question changes on the second request:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1",
)
# 示例占位资料;实际使用时换成每次请求保持不变的参考资料。
# 确保断点前的前缀至少有 1,024 tokens,否则不会创建缓存。
fixed_text = "This is fixed reference text. " * 600
def ask(question):
response = client.chat.completions.create(
model="qwen4-max",
messages=[{
"role": "user",
"content": [
{
"type": "text",
"text": fixed_text,
"prompt_cache_breakpoint": {"mode": "explicit"},
},
{"type": "text", "text": question},
],
}],
extra_body={
"enable_thinking": False,
"prompt_cache_options": {"mode": "explicit", "ttl": "1h"},
},
)
return response.usage.prompt_tokens_details
print("首个请求:", ask("Summarize the reference text."))
print("复用请求:", ask("List three key points from the reference text."))For the second request, check cached_tokens (cache reads) and cache_write_tokens (cache writes). A successful request does not by itself mean the cache was hit. Confirm that cached_tokens is greater than 0 and that the prefix and breakpoint position remain unchanged.
Obtain a QwenCloud API key for the Singapore region and securely set DASHSCOPE_API_KEY.
Ensure the fixed prefix before the breakpoint contains at least 1,024 tokens. Do not put per-turn variable content such as questions or timestamps in that prefix.
Send the first request to create the cache, then send a request as the same user with the same prefix and a different question.
Check cached_tokens and cache_write_tokens in the response's usage.prompt_tokens_details. The first request typically writes to the cache; reuse within the validity period increases the read count, while the write count is 0.
The documentation example uses qwen4-max as the model parameter and states that explicit caching supports only the Qwen4 series. The page supports the Chat Completions, Responses, and Anthropic Messages APIs; the DashScope API does not support explicit caching for the new Qwen4 models.
The explicit breakpoint marker is prompt_cache_breakpoint: {"mode":"explicit"}. The end of the content block containing the marker serves as the breakpoint; content from the start of the request through that breakpoint forms the cache prefix. The documentation recommends this field for new integrations. The compatible field cache_control: {"type":"ephemeral"} behaves the same way, but a request can use only one of these markers.
The cache prefix must contain at least 1,024 tokens. A cache hit requires the prefix to match exactly, the request to come from the same user, and the cache to remain within its validity period. The system looks back through at most 20 content blocks from a breakpoint, and each request can retain up to the 4 most recent valid breakpoints.
The TTL can only be 5m or 1h, and defaults to 5m. On a cache hit, it is renewed according to the TTL of the current request. The validity period starts when processing of the current request begins, and generation time counts toward it.
prompt_tokens_details.cached_tokens is the number of cached tokens read; cache_write_tokens is the number written and is equal to cache_creation_input_tokens. Do not add them together.
Explicit caching: Set a breakpoint on a content block; reuse is deterministic as long as the cached prefix is explicit and identical. The TTL is set in the top-level prompt_cache_options.ttl and applies to all breakpoints in the request. When setting a TTL, you must also set a cache breakpoint or enable automatic caching.
Implicit caching: When no cache parameters are set, the service automatically identifies common prefixes, but a cache hit is not guaranteed. Do not confuse implicit caching with no parameters and prompt_cache_options.mode="implicit"; the latter automatically places a breakpoint at the end of the current request's input and follows the TTL and billing rules for explicit caching described on this page.
If you move a breakpoint without retaining the old one, reads do not renew the old breakpoint. When the same prefix is written concurrently, the documentation does not guarantee that the latest expiration time will be retained.
enable_thinking=False in the example is only a configuration choice for controlling the example; it is not required to enable caching. The API key must match the regional endpoint.
On 2026-11-17, the official QwenCloud documentation for Qwen4 explicit caching was opened and checked through Tabbit. The example references the official OpenAI-compatible Chat Completions Python usage; no request was made with a real API key.
Qwen4-Max