Prompt caching

Prompt caching is automatic across the catalog: MindsHub marks the provider's cache breakpoints on the stable prefix of your request, so you get cache hits without doing anything. Cached reads bill at roughly a tenth of the input rate; cache writes are billable and never draw included tokens.

Works with

Every model whose provider caches: the Claude family (explicit breakpoints), the GPT and Grok families, Gemini, and Kimi (implicit). Per-model detail is on the capability matrix.

Request

Nothing is required. On Messages you can place explicit cache_control breakpoints, as Claude Code does, and a request that sends its own breakpoints is passed through exactly as sent rather than re-marked.

Chat Completions

# Caching is automatic. Keep the stable prefix (system prompt, tools) first.
response = client.chat.completions.create(
    model="sonnet",
    messages=[
        {"role": "system", "content": LONG_SYSTEM_PROMPT},
        {"role": "user", "content": "Summarize section 3."},
    ],
)
print(response.usage.prompt_tokens_details)

Responses

# Caching is automatic. `instructions` is the stable prefix.
response = client.responses.create(
    model="sonnet",
    instructions=LONG_SYSTEM_PROMPT,
    input="Summarize section 3.",
)
print(response.usage.input_tokens_details)

Messages

message = client.messages.create(
    model="sonnet",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": LONG_SYSTEM_PROMPT,
        "cache_control": {"type": "ephemeral"},   # explicit breakpoint
    }],
    messages=[{"role": "user", "content": "Summarize section 3."}],
)
print(message.usage.cache_read_input_tokens, message.usage.cache_creation_input_tokens)

Chat Completions

// Caching is automatic. Keep the stable prefix (system prompt, tools) first.
const response = await client.chat.completions.create({
  model: "sonnet",
  messages: [
    { role: "system", content: LONG_SYSTEM_PROMPT },
    { role: "user", content: "Summarize section 3." },
  ],
});
console.log(response.usage?.prompt_tokens_details);

Responses

// Caching is automatic. `instructions` is the stable prefix.
const response = await client.responses.create({
  model: "sonnet",
  instructions: LONG_SYSTEM_PROMPT,
  input: "Summarize section 3.",
});
console.log(response.usage?.input_tokens_details);

Messages

const message = await client.messages.create({
  model: "sonnet",
  max_tokens: 1024,
  system: [{ type: "text", text: LONG_SYSTEM_PROMPT, cache_control: { type: "ephemeral" } }],
  messages: [{ role: "user", content: "Summarize section 3." }],
});
console.log(message.usage.cache_read_input_tokens, message.usage.cache_creation_input_tokens);

Response

Cache activity shows up in usage:

API	Fields
Chat Completions	usage.prompt_tokens_details: {"cached_tokens": …, "cache_write_tokens": …}, present when the request touched the cache, reads or writes. prompt_tokens always includes cached tokens. cache_write_tokens is a MindsHub extension.
Responses	usage.input_tokens_details.cached_tokens
Messages	usage.cache_read_input_tokens and usage.cache_creation_input_tokens, always present. As in Anthropic's own API, input_tokens excludes cached tokens: the three input fields partition the prompt.

Don't treat the presence of prompt_tokens_details as "a cache read happened": writes alone populate it too.

Per-model differences

• Claude family: explicit cache_control breakpoints on Messages are honored; on the OpenAI-shaped APIs MindsHub places them for you. A request carrying its own breakpoints is never re-marked.
• GPT and Grok families: the provider caches implicitly; MindsHub derives a stable prompt_cache_key from your instructions and tools so repeated prefixes hit.
• Gemini and Kimi: implicit provider-side caching; reads are reported, writes are not billed separately.
• Fireworks-hosted models: no cache accounting is reported today.

Top-level cache_control (Anthropic's automatic-caching switch) on Messages is accepted and ignored; block-level breakpoints are what is honored.

Errors you can hit

None. Caching never fails a request. Cache writes are refused only as part of the request's overall funding check (402 wallet_empty). Prices are in Billing.