Pular para o conteúdo principal
Mantenha o início do prompt igual entre as solicitações, e o provedor o lê do cache em vez de processá-lo de novo: esses tokens são cobrados pela tarifa de leitura de cache e o primeiro token chega mais rápido. A maioria dos provedores armazena prefixos repetidos em cache por conta própria. O Claude só armazena em cache o que você marca com 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.
Depois, confira se funcionou:
  1. Envie a solicitação uma vez para gravar o cache.
  2. Envie-a de novo com o mesmo conteúdo armazenável em cache.
  3. Confira cached_tokens e cache_write_tokens no uso da resposta (veja Campos de uso e preços) e os medidores de cache nos detalhes da solicitação.
  4. Compare latência e custo ao longo de várias chamadas, não só da primeira.
Armazene em cache o conteúdo que se repete entre as solicitações: instruções de sistema longas, documentos reutilizados, exemplos few-shot, definições de ferramentas e resultados grandes de ferramentas que o turno seguinte envia de novo. Não marque conteúdo que muda a cada solicitação, entradas curtas e pontuais, nem dados que sua política não permite que o provedor armazene.
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

Um cache_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.
Use 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 um ttl opcional de 5m ou 1h.
  • prompt_cache_breakpoint: o {"mode": "explicit"} da OpenAI, com um ttl opcional de 30m ou 12h (veja Cache de 12 horas na OpenAI). Quando um bloco tem os dois, prompt_cache_breakpoint prevalece.
Em Chat Completions e Responses, as marcas são aceitas em partes de texto e imagem, em definições de ferramentas de função e em resultados de ferramentas cujo conteúdo é uma matriz de partes de texto. O Anthropic Messages aceita 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:
Aqui a solicitação usa 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ê define ttl: "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 (openai e openai-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 como prompt_cache_options.ttl ou prompt_cache_breakpoint.ttl no cabeçalho X-Phaseo-Dropped-Params e em meta.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 em provider_options.google.cached_content:
  • No Google AI Studio, cached_content só funciona com a sua própria chave de API do Google (BYOK). Com a chave do Phaseo, a solicitação retorna 400, porque o cache pertence à conta que o criou.
  • No Vertex AI, cached_content só funciona com a sua própria credencial do Vertex AI; com a credencial do Phaseo, a solicitação retorna 400. 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 como cachedContents/abc123 usa o project_id e a region do JSON da sua conta de serviço e retorna 400 se 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 definem previous_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

Mude reasoning_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.
Os detalhes da solicitação e os detalhamentos de preço usam estes medidores:

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. Envie prompt_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.
Última modificação em 12 de novembro de 2026