Domine os 3 pontos-chave do faturamento de cache do Claude: por que você deve usar o formato nativo da Anthropic para a invocação

Muitos desenvolvedores ficam confusos ao usar a API do Claude: mesmo ativando o prompt caching, por que o desconto não aparece na fatura?

A resposta costuma ser simples: você está usando o modo de compatibilidade da OpenAI, mas o faturamento de cache do Claude só suporta o formato nativo da Messages API da Anthropic.

Isso não é um bug, mas uma limitação de design explicada claramente na documentação oficial da Anthropic. Neste artigo, vamos explorar os princípios técnicos, as formas de chamada e a comparação de preços para que você entenda como usar o prompt caching do Claude do jeito certo e pare de gastar dinheiro à toa.

Princípios Fundamentais do Mecanismo de Prompt Caching do Claude

Antes de mergulharmos nas diferenças de formato, vamos entender como o prompt caching do Claude funciona na prática.

Como o cache do Claude funciona

Quando você envia uma requisição com o prompt caching ativado, o sistema segue este fluxo:

1. Verificação de cache: O sistema verifica se o prefixo do comando da requisição já foi armazenado em cache em consultas recentes.
2. Acerto de cache (Hit): Se encontrar uma correspondência, o sistema utiliza a versão em cache, reduzindo drasticamente o tempo de processamento e o custo.
3. Escrita em cache (Write): Se não houver correspondência, o sistema processa o comando completo e armazena o prefixo em cache após o início da resposta.

Conteúdos suportados pelo Prompt Caching do Claude

O prompt caching do Claude pode armazenar a maioria dos blocos de conteúdo de uma requisição:

• Tools: Definições de ferramentas no array tools.
• System messages: Blocos de conteúdo no array system.
• Text messages: Blocos de texto no array messages.content.
• Images & Documents: Imagens e documentos nas mensagens do usuário.
• Tool use & tool results: Blocos de conteúdo de chamadas e resultados de ferramentas.

🎯 Dica técnica: Para cenários que exigem chamadas frequentes com o mesmo comando de sistema, o prompt caching é a ferramenta de otimização de custos mais eficaz. Recomendamos utilizar a plataforma APIYI (apiyi.com) com o formato nativo da Anthropic para aproveitar ao máximo os descontos de faturamento por cache.

Formato Nativo da Anthropic vs. Modo de Compatibilidade OpenAI: Diferenças no Suporte ao Cache do Claude

Esta é a parte mais importante deste artigo — a diferença fundamental entre os dois formatos de chamada em relação à funcionalidade de cache do Claude.

Declaração oficial da Anthropic

De acordo com o texto original da documentação de compatibilidade do SDK da OpenAI da Anthropic:

"Prompt caching is not supported, but it is supported in the Anthropic SDK"
(O prompt caching não é suportado, mas é suportado no SDK da Anthropic)

Isso significa que, se você chamar o Claude através do modo de compatibilidade da OpenAI (endpoint /v1/chat/completions), não poderá usar a funcionalidade de prompt caching de jeito nenhum.

Comparação de funcionalidades entre os dois formatos de chamada da API do Claude

Por que o modo de compatibilidade OpenAI não suporta o cache do Claude

O modo de compatibilidade OpenAI foi projetado para testar e comparar as capacidades do modelo, e não para uso em ambiente de produção:

1. Diferenças de protocolo: O parâmetro cache_control é um campo nativo da Messages API da Anthropic e não possui um campo correspondente no formato chat completions da OpenAI.
2. Limitações de arquitetura: A camada de compatibilidade precisa converter o formato OpenAI para o formato Anthropic; durante esse processo de conversão, as informações de controle de cache são perdidas.
3. Prioridades: A Anthropic declarou que a prioridade da camada de compatibilidade é inferior à confiabilidade e integridade funcional da API nativa do Claude.

💡 Dica importante: Se o seu negócio depende do prompt caching para controlar custos, você deve usar o formato nativo Messages API da Anthropic, em vez do modo de compatibilidade OpenAI.

Detalhes de Preços do Prompt Caching do Claude: Economize até 90% nos custos

A estrutura de preços do prompt caching do Claude é o seu maior atrativo — o preço de leitura de um cache hit é de apenas 10% do preço base de entrada.

Comparação de preços de cache para todos os modelos Claude

MTok = Milhões de Tokens. Fonte dos dados: Página oficial de preços da Anthropic (fevereiro de 2026)

Regras de cálculo de preços do cache do Claude

O preço do cache segue 3 regras simples de multiplicadores:

• Escrita em cache de 5 minutos: Preço base de entrada × 1.25
• Escrita em cache de 1 hora: Preço base de entrada × 2.0
• Leitura de cache (Hit): Preço base de entrada × 0.1

Tomando o Claude Sonnet 4.6 como exemplo, suponha que você tenha um comando de sistema de 100.000 tokens:

💰 Otimização de custos: Para cenários que reutilizam o mesmo comando de sistema repetidamente, ao invocar a API do Claude no formato nativo da Anthropic através da plataforma APIYI (apiyi.com), você pode aproveitar ao máximo o prompt caching para obter uma economia de até 90%.

Código Prático de Claude Prompt Caching: Chamada no Formato Nativo da Anthropic

Abaixo, apresentamos exemplos de código específicos para mostrar como ativar corretamente o prompt caching do Claude.

Exemplo de Chamada Básica: Formato Nativo da Anthropic + Extended Thinking

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 16000,
    "stream": false,
    "thinking": {
      "type": "enabled",
      "budget_tokens": 10000
    },
    "messages": [
      {
        "role": "user",
        "content": "Quanto é 27 * 453?"
      }
    ]
  }'

Acima está uma chamada básica no formato nativo da Anthropic, utilizando o recurso de Extended Thinking. Agora, vamos ver como ativar o prompt caching com base nisso.

Modo de Cache Automático: A Maneira Mais Simples de Ativar o Cache do Claude

O cache automático é a forma mais fácil de habilitar o prompt caching do Claude — basta adicionar o campo cache_control no nível superior do corpo da requisição:

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "Você é um assistente especializado em documentação técnica, ajudando usuários a entender os métodos de uso e as melhores práticas de modelos de IA. Suas respostas devem ser precisas, concisas e práticas.",
    "messages": [
      {"role": "user", "content": "Quais são as principais características do Claude Sonnet 4.6?"},
      {"role": "assistant", "content": "O Claude Sonnet 4.6 é um modelo de alto desempenho lançado pela Anthropic..."},
      {"role": "user", "content": "Qual é o tamanho da sua janela de contexto?"}
    ]
  }'

No modo de cache automático, o sistema coloca automaticamente o ponto de interrupção do cache no último bloco de conteúdo que pode ser armazenado. Em conversas de várias rodadas, o ponto de cache avança automaticamente conforme a conversa cresce.

Modo de Cache Explícito: Controle Preciso do Conteúdo do Cache do Claude

Para cenários que exigem um controle refinado do comportamento do cache, você pode colocar o cache_control em blocos de conteúdo específicos:

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Você é um assistente de análise de documentos jurídicos, especializado em analisar cláusulas contratuais e riscos legais."
      },
      {
        "type": "text",
        "text": "[Insira aqui o texto completo de um contrato jurídico de 50 páginas... cerca de 100 mil tokens de conteúdo]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Por favor, analise as cláusulas principais e os riscos potenciais deste contrato."
      }
    ]
  }'

Neste exemplo, uma grande quantidade de documentos jurídicos é marcada como conteúdo de cache. A primeira requisição grava no cache; consultas subsequentes sobre o mesmo documento nos 5 minutos seguintes atingirão o cache, custando apenas 10% da taxa de leitura.

Cache de Longa Duração de 1 Hora: Estendendo o Tempo de Cache do Claude

Se o tempo padrão de 5 minutos não for suficiente, você pode optar pelo cache de 1 hora:

"cache_control": {"type": "ephemeral", "ttl": "1h"}

O cache de 1 hora é ideal para:

• Tarefas longas em fluxos de trabalho de agentes (mais de 5 minutos)
• Cenários onde o intervalo entre as falas do usuário pode exceder 5 minutos
• Cenários que exigem maior aproveitamento do limite de taxa (acertos no cache não consomem o rate limit)

🚀 Início Rápido: Recomendamos usar a plataforma APIYI (apiyi.com) para testar rapidamente o recurso de prompt caching do Claude. A plataforma oferece suporte total ao formato nativo da Messages API da Anthropic, incluindo o parâmetro cache_control, permitindo validar a integração em apenas 5 minutos.

Monitoramento de Desempenho e Depuração do Claude Prompt Caching

Após ativar o cache, você deve monitorar a eficácia através do campo usage na resposta da API.

Campos Chave na Resposta de Cache do Claude

{
  "usage": {
    "input_tokens": 50,
    "cache_creation_input_tokens": 100000,
    "cache_read_input_tokens": 0,
    "output_tokens": 500
  }
}

Fórmula de cálculo do total de tokens de entrada:

total_input = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Solução de Problemas: Por que o Cache do Claude não foi Ativado?

Se você notar que o cache nunca é atingido, verifique os seguintes pontos:

1. Formato de chamada incorreto: Usou o modo de compatibilidade OpenAI em vez do formato nativo da Anthropic.
2. Conteúdo inconsistente: O cache exige uma correspondência 100% exata do prefixo do comando.
3. Tokens insuficientes: Não atingiu o número mínimo de tokens exigido pelo modelo para cache.
4. Expiração por tempo: Mais de 5 minutos sem uso resultaram na expiração do cache.
5. Alteração de parâmetros: Mudanças em tool_choice, conteúdo de imagem ou parâmetros de thinking.

Requisitos Mínimos de Tokens para Cache por Modelo Claude

Se o seu comando tiver menos que o mínimo de tokens, o cache não será ativado mesmo com a tag cache_control — a requisição será processada normalmente, mas sem cache.

🎯 Dica de Depuração: Ao invocar a API do Claude na plataforma APIYI (apiyi.com), você pode verificar rapidamente se o cache está funcionando através do campo usage na resposta. Se tanto cache_read_input_tokens quanto cache_creation_input_tokens forem 0, significa que o recurso de cache não foi ativado corretamente.

FAQ sobre o Claude Prompt Caching

Q1: Posso usar o cache ao chamar o Claude no modo de compatibilidade com OpenAI?

Não. Esta é uma restrição declarada explicitamente pela Anthropic. O modo de compatibilidade com OpenAI (endpoint /v1/chat/completions) não suporta prompt caching. Você deve usar o formato nativo da Messages API da Anthropic (endpoint /v1/messages) para utilizar a funcionalidade de cache.

Através da plataforma APIYI (apiyi.com), você pode usar ambos os formatos para a invocação do modelo Claude — se precisar da função de cache, basta selecionar o endpoint /v1/messages.

Q2: A escrita no cache do Claude é mais cara que a entrada normal, ainda vale a pena?

Com certeza. A escrita no cache é apenas 25% mais cara que a entrada básica (com TTL de 5 minutos), mas um hit de cache custa apenas 10% do valor original. Se o mesmo conteúdo for usado mais de 2 vezes, você já recupera o investimento e começa a economizar. Tomando como exemplo um comando de sistema de 100 mil tokens:

• Sem cache: $0.30 por vez (Sonnet 3.5/3.7)
• Escrita em cache: $0.375 (apenas na primeira vez)
• Leitura de cache: $0.03 (cada vez subsequente)
• A partir da 2ª chamada, você já começa a economizar.

Q3: Como migrar do formato OpenAI para o formato nativo da Anthropic no código?

Principais pontos de mudança:

• Endpoint: /v1/chat/completions → /v1/messages
• Cabeçalho da requisição: Adicionar anthropic-version: 2023-06-01
• Formato da mensagem: A estrutura do array messages é basicamente a mesma
• Comando de sistema: Extraído de messages para um campo system independente
• Adição do parâmetro cache_control

A plataforma APIYI (apiyi.com) suporta ambos os endpoints simultaneamente. Ao migrar, você só precisa alterar o caminho e o formato da requisição, sem necessidade de trocar a chave API.

Q4: O cache do Claude pode ser compartilhado entre diferentes requisições?

O cache é compartilhado dentro do mesmo Workspace (desde 5 de fevereiro de 2026, a Anthropic mudou o isolamento de nível organizacional para nível de Workspace). O cache nunca é compartilhado entre organizações diferentes.

Q5: O cache e a Batch API podem ser usados juntos?

Sim. A Batch API oferece 50% de desconto, e o multiplicador de preço do cache é aplicado sobre esse valor já reduzido. A combinação de ambos permite a máxima otimização de custos. Recomendamos usar um TTL de cache de 1 hora em cenários de processamento em lote para aumentar a taxa de acerto (hit rate).

Resumo: 3 pontos fundamentais sobre o faturamento do Claude Prompt Caching

Com base na análise deste artigo, aqui estão os 3 pontos cruciais que você deve lembrar sobre o faturamento do prompt caching do Claude:

1. Suporte apenas ao formato nativo da Anthropic: A funcionalidade de cache está disponível apenas no endpoint /v1/messages; o modo de compatibilidade com OpenAI (/v1/chat/completions) não a suporta.
2. Custo de hit de cache é de apenas 10%: Você paga 25% a mais na primeira escrita, mas cada hit subsequente custa apenas um décimo do preço base. O investimento se paga em apenas 2 chamadas.
3. A forma correta de chamada é a chave: Use o parâmetro cache_control: {"type": "ephemeral"} e certifique-se de atingir o requisito mínimo de tokens de cache do modelo.

Recomendamos experimentar a funcionalidade completa do Claude prompt caching através da plataforma APIYI (apiyi.com). A plataforma oferece suporte total à Messages API nativa da Anthropic, ajudando você a utilizar os modelos Claude com o melhor custo-benefício.

Referências

1. Documentação oficial de Prompt Caching da Anthropic: Detalhes sobre a funcionalidade de cache da API do Claude

   • Link: platform.claude.com/docs/en/build-with-claude/prompt-caching

2. Página oficial de preços da Anthropic: Preços dos modelos Claude e do cache

   • Link: platform.claude.com/docs/en/about-claude/pricing

3. Documentação de compatibilidade do SDK da OpenAI: Explicação das limitações de recursos no modo de compatibilidade

   • Link: platform.claude.com/docs/en/api/openai-sdk

📝 Autor: Equipe APIYI | Equipe Técnica APIYI, especializada em integração de APIs de Modelos de Linguagem Grandes e compartilhamento de conhecimento técnico. Acesse apiyi.com para mais tutoriais técnicos.