--- title: How does OpenAI's Responses API prompt-cache prewarming work? url: https://deepthinkingai.org/openai-prompt-cache-prewarming/ published: 2026-09-22 author: Shekhar Singh topic: AI Engineering tags: prompt-caching, openai, responses-api, latency site: DeepThinking AI --- # How does OpenAI's Responses API prompt-cache prewarming work? **Summary:** openai-python v3.15.0 adds a prewarm field to the Responses API's prompt cache options. Setting it true forces generate to false, writing the cache with no output, at a TTL fixed to 30 minutes. Claude has offered the same effect since launch via a max_tokens=0 request, with a 5 minute default or a paid 1 hour TTL. ## Key takeaways - OpenAI's prewarm field forces the generate field to false, so a priming call always returns empty output. - The Responses API prompt cache TTL is fixed at 30 minutes, with no other value documented in the SDK today. - Claude has supported cache priming since launch through a plain request with max_tokens set to 0. - Claude's cache TTL defaults to 5 minutes and extends to 1 hour at twice the normal write price. - OpenAI ships prewarming as a WebSocket client event inside a persistent Responses session. It is not a parameter on the plain HTTP endpoint. A prompt cache only helps on the request that reuses it. The first request on a cold cache still pays full latency, and if that first request is the one your user is waiting on, caching has not saved them anything. OpenAI's Responses API just shipped a field built specifically to move that cost earlier, and because it landed inside a beta SDK release with no accompanying blog post, almost nothing has explained what it actually does. ## What does OpenAI's Responses API prewarm field do? `openai-python` v3.15.0, released 18 September 2026, adds a `prewarm` boolean to `ResponseCreatePromptCacheOptions`. The SDK docstring is explicit: it "prepares the prompt cache without generating output" and "overrides the generate field to false" when set true. The field arrived alongside a second new feature in the same release, managed Responses WebSocket sessions, and `prewarm` lives inside that mechanism rather than as a parameter on the plain `POST /v1/responses` endpoint. A client opens a persistent WebSocket connection, then sends a `ResponseCreate` client event, which the SDK describes as carrying "the same top-level fields as `POST /v1/responses`, plus WebSocket-only envelope metadata" such as a `stream_id`. Setting `prompt_cache.prewarm` to true on one of those events writes the cache and returns nothing, by design. **A prewarmed turn inside a Responses WebSocket session** ```mermaid sequenceDiagram participant Client as Client participant ResponsesAPI as Responses API Client->>ResponsesAPI: ResponseCreate, prompt_cache.prewarm=true ResponsesAPI->>Client: cache write completes, empty content Client->>ResponsesAPI: ResponseCreate, real user turn ResponsesAPI->>Client: response served from warm cache ``` - ResponseCreate, prompt_cache.prewarm=true: generate forced to false - cache write completes, empty content: billed as a cache write - response served from warm cache: faster first token The priming call and the real call share one persistent WebSocket session. The first writes the cache and returns nothing by design; the second is the one the user actually waits on. ## How does prewarm interact with the generate field? The interaction is a one-way override rather than an independent flag. `generate` normally controls whether a `ResponseCreate` event produces model output at all, and the prewarm docstring states that setting `prewarm` true forces `generate` to false regardless of what you passed. There is no combination that primes the cache and returns a real answer in the same call: you cannot ask for both. That matters for how you wire it into an application. A prewarm call has to be treated as a side effect you fire and never read from, sent on its own client event, ahead of the request whose output you actually want. Sending it as an afterthought attached to a real turn does nothing, because by definition that combination never generates a response for the user to see. ## What do the mode and ttl fields on the cache options control? Two more fields sit on the same `ResponseCreatePromptCacheOptions` object. `mode` is a literal `"implicit"` or `"explicit"` that controls whether the API creates cache breakpoints automatically as a conversation grows or only where the caller places them, independent of whether a given call prewarms. `ttl` is typed to accept only the literal string `"30m"`, which the docstring calls "the minimum lifetime for cache breakpoints." No shorter or longer value is defined in the SDK today. A fourth field, `comparison_response_id`, lets a caller reference an earlier response for diagnostic purposes when checking whether a cache actually reused work. Together these four fields are a more explicit cache control surface than a single boolean, but the fixed TTL is a real constraint: there is currently no way to request a shorter window for a tight request loop or a longer one for a slow-moving conversation. **Prompt cache TTL by provider and tier** | Item | Value (minutes) | Note | |---|---|---| | OpenAI Responses, fixed | 30 | only value the field accepts today | | Claude, default | 5 | ephemeral, no extra cost | | Claude, extended | 60 | costs 2x the write price | OpenAI ships one TTL. Claude ships two, and the longer one is a paying choice rather than a fixed ceiling, which changes what "prewarm early" means on each platform. ## How does this compare with Claude's own cache priming? [Anthropic documents the same effect](/prompt-caching-economics/) through a plain request rather than a dedicated field: set `max_tokens` to 0 and put `cache_control` on the prefix you want stored. The call returns immediately with an empty `content` array and `stop_reason` of `max_tokens`, and `usage.cache_creation_input_tokens` confirms the write. Claude's TTL is configurable rather than fixed: 5 minutes by default at no extra cost, or 1 hour at twice the normal cache-write price if you need the window open longer. OpenAI's version is newer, self-documenting through a named field instead of a side effect of `max_tokens=0`, and it sits inside a session model built for reuse across many turns. Claude's version has existed since prompt caching launched and gives you a price-versus-duration choice that OpenAI's fixed 30 minutes does not. ## When does prewarming actually change what a user experiences? Prewarming only pays off when you can predict a turn before it arrives and the gap before it lands fits inside the TTL. A support widget that starts loading a session the moment a user opens a chat window, a voice agent that knows a caller is about to speak, or a batch job that primes a shared system prompt before fanning out to workers are all real cases. A one-shot API call with no advance signal is not, because there is nothing earlier to prewarm ahead of. The [session model changes covered when Claude added on-demand compaction](/claude-compaction-modes/) point at the same shift: both vendors are building explicit controls around what used to be an implicit side effect of normal traffic, and prewarming is the caching half of that move. Treat the fixed 30 minute window as the real limit on OpenAI today, and budget Claude's paid 1 hour tier only where the gap between turns actually needs it. ## Decide whether and how to prewarm a prompt cache The two platforms solve the same problem with a different shape, so the ordering below branches on which one you are calling. 1. **Confirm you are calling a persistent Responses WebSocket session**: The prewarm field lives on ResponseCreatePromptCacheOptions, a WebSocket client event. It is unavailable on the plain POST /v1/responses endpoint, so check which client you are using before reaching for it. 2. **Send the priming call before the user needs an answer**: A login screen, a typing indicator or a queued job are all points where you know a turn is coming. Fire the prewarm request there and treat it as fire and forget, since generate is forced to false and there is nothing to read from the response. 3. **Pick a cache mode that matches how your prefix grows**: Use explicit mode when the cached prefix is fixed, such as a static system prompt, and implicit when it grows turn by turn, such as accumulating conversation history. 4. **Time the real call inside the TTL window**: OpenAI's 30 minute window is fixed, so a prewarm sent more than 30 minutes before the real turn has already expired. On Claude, choose the 5 minute default for tight loops and pay for the 1 hour tier only when the gap between turns regularly exceeds a few minutes. 5. **On Claude, build the prewarm call yourself**: There is no dedicated field. Send a normal request with max_tokens set to 0 and cache_control on the prefix you want stored, then check usage.cache_creation_input_tokens to confirm the write happened rather than assuming it did. 6. **Measure the win before trusting it**: Compare time to first token on a primed call against a cold one on the same route. If the gap disappears after a deploy, something changed the prefix above the breakpoint and the cache is silently missing again. ## Frequently asked questions ### What does OpenAI's prewarm field actually do? It sends a request that loads your prompt prefix into the cache without generating a model response. The SDK docstring states it overrides the generate field to false, so the call always returns empty content, and you pay the cache write charge rather than a generation charge. ### Does prewarm cost the same as a normal cache write? The SDK source does not publish a distinct price for it. It is described as a normal cache write, which OpenAI's pricing already charges more than a base input token, so prewarming trades that one-time premium for a guaranteed cache hit on the next real request. ### Can you prewarm a Claude prompt cache the same way? Yes. Anthropic's documented pattern is a request with max_tokens set to 0 and cache_control on the static prefix. It returns immediately with an empty content array and stop_reason max_tokens, and usage.cache_creation_input_tokens confirms the write landed. ### What is the difference between implicit and explicit cache mode in OpenAI's API? The mode field on ResponseCreatePromptCacheOptions controls whether the API creates cache breakpoints automatically as the conversation grows (implicit) or only where you place them (explicit). This is a separate control from prewarm, which just decides whether a given call produces output. ### Why is OpenAI's cache TTL fixed at 30 minutes? The SDK types the ttl field as a literal accepting only the string "30m", so there is currently no shorter or longer option to request. That may change as the feature leaves beta, but nothing in the source or release notes suggests a second value is coming soon. ## Sources - [openai-python v3.15.0 release notes](https://github.com/openai/openai-python/releases/tag/v3.15.0). OpenAI, 2026-09-18 - [Add prompt-cache prewarming (#3888)](https://github.com/openai/openai-python/pull/3888). OpenAI, 2026-09-17 - [responses_client_event_param.py, ResponseCreatePromptCacheOptions](https://github.com/openai/openai-python/blob/main/src/openai/types/responses/responses_client_event_param.py). OpenAI, 2026-09-18 - [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching). Anthropic --- Canonical HTML: https://deepthinkingai.org/openai-prompt-cache-prewarming/