# Prompt caching and reasoning — parameter-level mapping across four providers

Status: parameters from generated/parameters.json (prompt_cache_*, reasoning.*, cache_control*, thinking.*, output_config.*, xAI prompt_cache_key / reasoning_effort / include, Gemini cachedContent, generationConfig.thinkingConfig.*), per-model facts from generated/models.json and generated/compatibility/{anthropic,gemini}-feature-model-matrix.json, prices from generated/pricing.json; live observations quoted from docs/openai/prompt-caching.md, docs/openai/reasoning.md, docs/anthropic/prompt-caching.md, docs/anthropic/thinking.md, docs/anthropic/effort.md, docs/xai/prompt-caching.md, docs/xai/reasoning.md, docs/gemini/context-caching.md, docs/gemini/thinking.md (2026-09-18/19). Gemini explicit caching is ACCOUNT_RESTRICTED on this free-tier key (429 … limit=0); size validation and CRUD shapes were LIVE_VERIFIED. Sources: https://developers.openai.com/api/docs/guides/prompt-caching · https://developers.openai.com/api/docs/guides/reasoning · https://platform.claude.com/docs/en/build-with-claude/prompt-caching · https://platform.claude.com/docs/en/build-with-claude/extended-thinking · https://platform.claude.com/docs/en/build-with-claude/effort · https://docs.x.ai/developers/model-capabilities/text/prompt-caching · https://docs.x.ai/developers/model-capabilities/text/reasoning · https://ai.google.dev/gemini-api/docs/caching · https://ai.google.dev/gemini-api/docs/thinking Last verified: 2026-09-18

# Part A — Prompt / context caching

# A1. Mechanics

# A2. Prices

# A3. The same cached call on all four providers

// OpenAI (GPT-5.6+ explicit mode; on older models omit prompt_cache_options — caching is implicit)
{"model": "gpt-5.6-terra", "prompt_cache_key": "tenant-42",
 "prompt_cache_options": {"mode": "explicit", "ttl": "30m"},
 "input": [{"role": "developer", "content": [{"type": "input_text", "text": "<~2k tokens of stable policy>", "prompt_cache_breakpoint": {"mode": "explicit"}}]},
           {"role": "user", "content": "Question of the day"}],
 "max_output_tokens": 200}

// Anthropic (explicit breakpoint on the system block, 1-hour TTL)
{"model": "claude-sonnet-5", "max_tokens": 200,
 "system": [{"type": "text", "text": "<~2k tokens of stable policy>", "cache_control": {"type": "ephemeral", "ttl": "1h"}}],
 "messages": [{"role": "user", "content": "Question of the day"}]}

// xAI (automatic; the routing key keeps every request of this tenant on the same server)
{"model": "grok-4.3", "prompt_cache_key": "tenant-42",
 "instructions": "<~2k tokens of stable policy>",
 "input": [{"role": "user", "content": "Question of the day"}],
 "reasoning": {"effort": "low"}, "max_output_tokens": 200}

// Gemini — explicit: POST /v1beta/cachedContents (once) …
{"model": "models/gemini-3.8-flash", "displayName": "tenant-42-policy", "ttl": "3600s",
 "systemInstruction": {"parts": [{"text": "<~4k tokens of stable policy>"}]}}
// … then POST /v1beta/models/gemini-3.8-flash:generateContent (do NOT repeat the cached systemInstruction)
{"cachedContent": "cachedContents/abc123",
 "contents": [{"role": "user", "parts": [{"text": "Question of the day"}]}],
 "generationConfig": {"maxOutputTokens": 200}}
// implicit alternative: send the same ≥4,096-token prefix first in `contents` on every call and watch usageMetadata.cachedContentTokenCount

Anthropic shortcut equivalent to the implicit modes: top-level "cache_control": {"type": "ephemeral"}.

# A4. Portability notes

• Ordering discipline is identical everywhere: stable content first (instructions, tools, schema), volatile content last.
• Keys: OpenAI and xAI key the cache per prompt_cache_key (xAI: sticky routing); Anthropic per exact bytes; Gemini explicit caches per resource name and implicit per prefix.
• Token accounting: Anthropic's input_tokens excludes cached tokens; OpenAI's, xAI's and Gemini's promptTokenCount include them (cached_tokens / cachedContentTokenCount is a subset).
• Reasoning and caching interact on every provider: OpenAI/xAI replay encrypted_content, Anthropic keeps thinking blocks, Gemini keeps thoughtSignature — dropping them breaks the prefix (xAI: "top cause of cache misses").
• Compaction resets the prefix on OpenAI/Anthropic/xAI (compaction item/block); keep a breakpoint or a cachedContents resource on the system prompt so only the summary is rewritten.
• Cost of a miss: only Anthropic (1.25×/2×) and GPT-5.6+ (1.25×) charge writes; Gemini charges storage time for explicit caches; xAI never charges for filling the cache.

# Part B — Reasoning / thinking

# B1. Controls

# B2. Response shapes

# B3. Per-model reasoning modes

# B4. The same "think hard, show a summary" request

// OpenAI
{"model": "gpt-5.6-terra", "input": "How many r's in strawberry? Explain briefly.",
 "reasoning": {"effort": "high", "summary": "auto"}, "max_output_tokens": 600}

// Anthropic (adaptive model)
{"model": "claude-sonnet-5", "max_tokens": 600,
 "thinking": {"type": "adaptive", "display": "summarized"}, "output_config": {"effort": "high"},
 "messages": [{"role": "user", "content": "How many r's in strawberry? Explain briefly."}]}

// xAI — Responses (summary) …
{"model": "grok-4.6", "input": "How many r's in strawberry? Explain briefly.",
 "reasoning": {"effort": "high", "summary": "auto"}, "max_output_tokens": 600}
// … or Chat Completions (full reasoning_content text)
{"model": "grok-4.6", "reasoning_effort": "high",
 "messages": [{"role": "user", "content": "How many r's in strawberry? Explain briefly."}]}

// Gemini
{"contents": [{"role": "user", "parts": [{"text": "How many r's in strawberry? Explain briefly."}]}],
 "generationConfig": {"thinkingConfig": {"thinkingLevel": "high", "includeThoughts": true}, "maxOutputTokens": 600}}

Read the summary from output[].type == "reasoning" → summary[].text (OpenAI, xAI Responses), choices[0].message.reasoning_content (xAI Chat), content[].type == "thinking" → thinking (Anthropic), or parts[] with thought: true (Gemini); billed tokens from reasoning_tokens / thinking_tokens / reasoning_tokens / thoughtsTokenCount.

# B5. Caching × reasoning interactions

Related: pricing · state-management · features · docs/openai/prompt-caching.md · docs/anthropic/prompt-caching.md · docs/xai/prompt-caching.md · docs/gemini/context-caching.md · docs/openai/reasoning.md · docs/anthropic/thinking.md · docs/xai/reasoning.md · docs/gemini/thinking.md.