cache_control.
O cache de prompts continua executando a inferência em cada solicitação. Ele não devolve uma resposta anterior para uma solicitação idêntica.
Armazenar um prompt em cache
Marque o último bloco da parte estável. Tudo até esse bloco, inclusive, é armazenado em cache.- Envie a solicitação uma vez para gravar o cache.
- Envie-a de novo com o mesmo conteúdo armazenável em cache.
- Confira
cached_tokensecache_write_tokensno uso da resposta (veja Campos de uso e preços) e os medidores de cache nos detalhes da solicitação. - Compare latência e custo ao longo de várias chamadas, não só da primeira.
O Phaseo envia a cada provedor apenas os controles de cache que ele documenta e remove os demais. Os controles de cache nunca excluem um provedor do roteamento. A página de cada modelo lista seus preços de leitura e gravação de cache.
Quais provedores armazenam em cache automaticamente
Outros provedores compatíveis com OpenAI recebem
prompt_cache_key quando a API deles o aceita, e nenhum outro controle de cache. O Phaseo sempre envia um hash do seu espaço de trabalho e da chave, nunca a própria chave; veja Afinidade com o provedor.
Controles de cache
Deixar o Phaseo posicionar os pontos de interrupção do Claude
Umcache_control de nível superior em Chat Completions, Responses ou Anthropic Messages ativa o cache nas rotas do Claude, e o Phaseo posiciona os pontos de interrupção para você. Os outros provedores o ignoram.
ttl: "5m" (o padrão) para contexto compartilhado de curta duração e ttl: "1h" quando o modelo aceitar entradas de cache mais duradouras. Um cache_control de nível superior também mantém a conversa em um único provedor; veja Afinidade com o provedor.
provider_options.anthropic.cache_control é a mesma configuração e também aceita um scope. Quando uma solicitação envia os dois, o valor de provider_options prevalece:
Use
agent em loops de ferramentas com várias etapas. all_text e last_user_message não marcam mensagens que contêm apenas resultados de ferramentas, então o prefixo em cache para de crescer. Valores de scope não reconhecidos são tratados como agent.
Os pontos de interrupção que você define nos blocos prevalecem sobre a política padrão e contam para o limite de quatro por solicitação da Anthropic: a política padrão para de adicionar marcas ao chegar a quatro. Se os seus próprios blocos tiverem mais de quatro marcas, o Phaseo mantém a primeira e as três mais recentes e remove as outras, para que a solicitação não seja rejeitada.
Pontos de interrupção de cache em blocos
Uma marca de cache em um bloco de conteúdo armazena em cache tudo até esse bloco, inclusive. O Phaseo aceita duas grafias:cache_control:{"type": "ephemeral"}, com umttlopcional de5mou1h.prompt_cache_breakpoint: o{"mode": "explicit"}da OpenAI, com umttlopcional de30mou12h(veja Cache de 12 horas na OpenAI). Quando um bloco tem os dois,prompt_cache_breakpointprevalece.
cache_control onde a Anthropic aceita: blocos de texto de system, blocos de texto e imagem das mensagens, blocos de resultado de ferramenta e definições de ferramentas. Quando uma solicitação tem vários TTLs, a Anthropic exige que os pontos de interrupção de 1h venham antes dos de 5m.
Cada provedor recebe a marca no próprio formato:
Marcas em definições de ferramentas só chegam às rotas do Claude, ao Alibaba Model Studio, à Venice e aos modelos Claude e Gemini 2.5 da Inference.net; a OpenAI não aceita pontos de interrupção em ferramentas. Remover uma marca não altera o resto do prompt, então o prefixo em cache corresponde a uma solicitação sem marcas.
O Amazon Bedrock e o Google Vertex AI armazenam o Claude 3.7 Sonnet, o 3.5 Sonnet e o 3 Opus em cache por apenas 5 minutos, e o Bedrock pode rejeitar um
ttl nesses modelos. Nessas rotas, o Phaseo envia seus pontos de interrupção sem ttl, para que fiquem em cache por 5 minutos, e informa um 1h removido como cache_control.ttl no cabeçalho X-Phaseo-Dropped-Params e em meta.routing.dropped_params. A Inference.net documenta pontos de interrupção sem ttl, então o Phaseo remove e informa um ttl ali da mesma forma, e as gravações são cobradas como gravações de 5 minutos.
Retenção e opções da OpenAI
Os controles de cache da OpenAI dependem da geração do modelo. O Phaseo envia cada um apenas onde é aceito:
O modo
explicit armazena em cache apenas os pontos de interrupção que você posiciona. A DeepInfra também exige prompt_cache_key em todas as solicitações da sessão. O Phaseo só envia um 1h da Moonshot AI para rotas do Kimi K3 que têm preço de gravação de 1 hora, então essas gravações são cobradas por esse preço; nos demais casos, ele remove o ttl e o informa como prompt_cache_options.ttl no cabeçalho X-Phaseo-Dropped-Params. Os outros provedores não recebem nenhum dos dois campos.
Envie qualquer um dos campos no nível superior ou em provider_options.openai. Quando os dois estão presentes, o valor de nível superior prevalece:
24h.
Cache de 12 horas na OpenAI
No GPT-5.6 e posteriores, a OpenAI mantém uma entrada de cache por pelo menos 12 horas quando você definettl: "12h", seja para a solicitação inteira em prompt_cache_options, seja para um ponto de interrupção em prompt_cache_breakpoint. Um ponto de interrupção sem ttl próprio usa o da solicitação. A OpenAI cobra uma gravação de 12 horas a 2.5× a tarifa de entrada e uma gravação de 30 minutos a 1.25×; as leituras de cache custam o mesmo nos dois casos.
- A OpenAI documenta a duração de 12 horas apenas na Responses API dela. Uma solicitação de Chat Completions que a peça é executada na Responses API da OpenAI, e a resposta mantém o formato de Chat Completions.
- As rotas que aceitam um cache de 12 horas são tentadas primeiro: a API da própria OpenAI (
openaieopenai-eu), em um modelo GPT-5.6 ou posterior cuja tabela de preços tenha um preço de gravação de 12 horas. Qualquer outra rota, como a Azure OpenAI, outro provedor ou um modelo anterior ao GPT-5.6, recebe a solicitação sem ele, então vale o padrão de 30 minutos. A solicitação continua sendo executada, e o campo removido é informado comoprompt_cache_options.ttlouprompt_cache_breakpoint.ttlno cabeçalhoX-Phaseo-Dropped-Paramse emmeta.routing.dropped_params.
Usar um cache explícito do Gemini
O Gemini 2.5 e posteriores armazenam em cache implicitamente, sem nada a enviar. Para usar um cache explícito que você criou com a API de cache do Google, passe o nome dele emprovider_options.google.cached_content:
- No Google AI Studio,
cached_contentsó funciona com a sua própria chave de API do Google (BYOK). Com a chave do Phaseo, a solicitação retorna400, porque o cache pertence à conta que o criou. - No Vertex AI,
cached_contentsó funciona com a sua própria credencial do Vertex AI; com a credencial do Phaseo, a solicitação retorna400. Envie o nome completo do cache,projects/{project}/locations/{location}/cachedContents/{id}, e o Phaseo envia a solicitação para esse projeto e local. Um nome curto comocachedContents/abc123usa oproject_ide aregiondo JSON da sua conta de serviço e retorna400se algum deles estiver faltando. - O Google não oferece caches explícitos no Gemini 4 Argon e posteriores.
provider_options.google.cache_control e provider_options.google.cache_ttl são aceitos, mas não são enviados ao Google.
Responses: enviar a conversa inteira
O Phaseo não armazena respostas. Solicitações que definemprevious_response_id ou conversation retornam 400 unsupported_param, então envie a conversa inteira em input a cada etapa. A abertura estável dela é o prefixo que fica em cache. Em loops de ferramentas, envie de volta também os itens de saída reasoning; veja Raciocínio em loops de ferramentas.
Mudar o esforço de raciocínio no meio da conversa
Mudereasoning_effort (Chat Completions) ou reasoning.effort (Responses) entre solicitações, e o Phaseo mantém o cache de prompts do Claude: ele envia a mudança como um marcador de esforço dentro de messages em vez de um novo esforço de nível superior. Isso funciona desde que você envie o raciocínio do Claude de volta sem alterações. No Anthropic Messages, você mesmo envia o marcador. Veja Mudar o esforço de raciocínio no meio da conversa.
Campos de uso e preços
Todos os endpoints de texto informam leituras e gravações de cache. Chat Completions e Responses seguem a semântica da OpenAI: a contagem de entrada inclui as leituras e gravações de cache. O Anthropic Messages segue a da Anthropic:input_tokens as exclui.
Em Chat Completions e Responses, a entrada sem cache é a entrada total menos as leituras de cache menos as gravações de cache. Respostas do Anthropic Messages em streaming trazem os campos de cache em
message_delta. O uso de Chat Completions não tem divisão por duração, porque a OpenAI não documenta nenhuma ali; os detalhes da solicitação ainda a registram.
Respostas anteriores informavam as gravações de cache como
output_tokens_details.cached_tokens (completion_tokens_details.cached_tokens em Chat Completions), e as rotas do Claude deixavam as leituras e gravações de cache fora de input_tokens em Chat Completions e Responses. Nada disso vale mais: leia as gravações em cache_write_tokens. Respostas do Anthropic Messages sem streaming retornavam cache_creation_input_tokens: null; agora retornam as contagens reais.Como os tokens em cache são cobrados
O Phaseo cobra cada token de entrada uma vez, por uma única tarifa: a entrada sem cache pela tarifa de entrada, as leituras de cache pela tarifa de leitura de cache e as gravações de cache pela tarifa de gravação de cache, ou pelas tarifas de 5 minutos e 1 hora (Claude) ou de 30 minutos e 12 horas (OpenAI) quando o provedor as precifica separadamente. Alguns provedores contam as gravações de cache dentro do total de entrada e outros as informam à parte; de qualquer forma, um token gravado nunca é cobrado também como entrada comum. Por exemplo, com tarifas ilustrativas de $5.00 por 1M de tokens de entrada, $0.50 para leituras de cache, $6.25 para gravações de cache de 30 minutos e $30.00 para saída, uma solicitação com 53.100 tokens de entrada, dos quais 48.000 são leituras de cache e 3.000 são gravações de cache, mais 850 tokens de saída, custa:
Se 2.000 dessas gravações tivessem duração de 12 horas, elas custariam $12.50 por 1M em vez de $6.25, e a solicitação custaria $0.09125.
Alguns provedores não dão desconto para tokens em cache em alguns modelos. As páginas desses modelos mostram o mesmo preço para entrada e leituras de cache.
Quando uma rota ainda não tem preço de cache
Se um provedor informar tokens em cache em uma rota que ainda não tem preço de cache no catálogo, a solicitação não falha:- As leituras de cache são cobradas pela tarifa de entrada da rota.
- As gravações de cache são cobradas pela tarifa de entrada vezes o multiplicador de gravação documentado pelo provedor.
- A linha de preço é marcada com
pricing_fallback: "input_rate".
Em uma rota do Claude cujo catálogo tem um único preço de gravação de cache, esse preço é a tarifa de 5 minutos. As gravações que o provedor informa como gravações de 1 hora são cobradas a 2× a tarifa de entrada, em uma linha
cached_write_text_tokens_1h marcada com pricing_fallback: "input_rate".
O message_delta final de uma resposta do Claude em streaming informa o total de gravações de cache sem a divisão por TTL. As gravações além da divisão são cobradas como gravações de 5 minutos, porque gravações de ferramentas do servidor podem usar 5 minutos mesmo quando a solicitação pede 1 hora.
Afinidade com o provedor
Um cache de prompt fica em um provedor e, muitas vezes, em uma região ou implantação desse provedor. O Phaseo mantém as solicitações relacionadas no provedor e na rota que as atenderam, para que um loop de agente não pague para reconstruir o cache em outro lugar. Envieprompt_cache_key ou session_id, ou ative o cache com cache_control (no nível superior, em provider_options.anthropic.cache_control ou como marca cache_control ou prompt_cache_breakpoint em um bloco de mensagem ou ferramenta), para fixar uma conversa. O Phaseo a fixa no provedor e na rota que atenderam a primeira solicitação bem-sucedida, e as solicitações seguintes com a mesma chave também vão para lá. As fixações são mantidas por espaço de trabalho, endpoint e modelo.
Quanto tempo uma fixação dura depende da retenção de cache do provedor:
Uma fixação só muda quando o provedor falha (um disjuntor aberto ou uma taxa alta de erros recentes), quando a cota gerenciada do Phaseo nesse provedor se esgota, ou quando a rota, predefinição, guardrail ou política de solicitação ativa não o permite mais. A solicitação então passa para uma alternativa, e a fixação vai para o provedor que a atendeu. Os detalhes da solicitação registram isso como
sticky_routing.demotionReason nos diagnósticos de roteamento. Solicitações fixadas não são usadas para sondar provedores em recuperação.
Sem chave, session_id ou marca de cache, o Phaseo ainda fixa o contexto de abertura por 15 minutos em um provedor que informou uma leitura ou gravação de cache para ele, desde que a entrada em cache desse provedor seja mais barata que a entrada padrão.
O Phaseo envia aos provedores um hash do seu espaço de trabalho e de prompt_cache_key, nunca a chave bruta, então a mesma chave em dois espaços de trabalho nunca compartilha um cache de provedor. Com apenas um session_id, o Phaseo deriva esse hash da sessão para OpenAI, xAI, Fireworks e Cerebras. Fireworks, Cloudflare Workers AI e Baseten também o recebem no cabeçalho x-session-affinity, a Morph no cabeçalho x-session-id e a xAI como x-grok-conv-id, a menos que você defina provider_options.xai.conversation_id. As respostas continuam ecoando o seu próprio prompt_cache_key.
Defina provider.cache_aware_routing como false para desativar isso em uma solicitação. Defina routing.session_affinity como false quando a solicitação tiver um session_id, mas deve usar apenas o roteamento normal baseado em contexto; nesse caso, o Phaseo também deixa de derivar uma chave de cache de provedor a partir da sessão. Para saber como a afinidade se combina com a ordem de provedores e as alternativas, veja Roteamento e alternativas. Todos os campos de cache também estão listados na referência de parâmetros.