Dominando os 3 Mecanismos Centrais de Cobrança do Cache da API Claude: Comparação de Preços de Escrita em Cache de 5 Minutos vs 1 Hora e Explicação Detalhada do Isolamento de Cache entre Contas

Nota do autor: Análise profunda do mecanismo de cobrança de cache da API Claude, comparando as diferenças de preço entre a gravação de cache de 5 minutos e 1 hora, respondendo à questão do acerto de cache entre contas e comparando as diferenças de cobrança de cache entre a AWS Bedrock e a API oficial da Anthropic.

O Prompt Caching da API Claude é um meio central para reduzir os custos de chamadas de API, mas muitos desenvolvedores têm dúvidas sobre os detalhes da cobrança de cache: Como escolher entre o cache de 5 minutos e o de 1 hora? O cache pode ser compartilhado entre contas? Qual a diferença na cobrança de cache entre a AWS Bedrock e a oficial?

Valor principal: Após ler este artigo, você entenderá completamente os 3 mecanismos centrais da cobrança de cache da API Claude, dominará o método de escolha da estratégia de cache ideal e evitará desperdícios desnecessários de custos.

Pontos Principais da Cobrança de Cache da API Claude

Taxa Base da Cobrança de Cache do Claude

O Prompt Caching da API Claude adota um sistema unificado de cobrança por taxa, independentemente do modelo usado (Opus 4.6, Sonnet 4.6 ou Haiku 4.5). As regras de taxa para operações de cache são completamente consistentes:

• Gravação de Cache (TTL de 5 minutos): Preço base de entrada × 1.25
• Gravação de Cache (TTL de 1 hora): Preço base de entrada × 2.0
• Leitura de Cache (acerto): Preço base de entrada × 0.1

Isso significa que a cada acerto de cache, você paga apenas 10% do preço padrão de entrada. Tomando o Claude Sonnet 4.6 como exemplo, o preço padrão de entrada é $3/MTok, e o preço de acerto de cache é apenas $0.3/MTok, economizando 90% do custo de entrada.

Cálculo de Retorno do Investimento na Cobrança de Cache do Claude

Entender o custo-benefício do cache é muito importante. A gravação de cache tem um custo adicional, mas a leitura de cache é extremamente barata. A chave é: quantas vezes o cache precisa ser acessado para começar a "se pagar"?

• Cache de 5 minutos: Gravação 1.25x + Leitura 0.1x = Após a primeira gravação, basta 1 acerto para se pagar (porque a leitura normal é 1x, e a leitura de cache é 0.1x, economizando 0.9x > o adicional pago de 0.25x)
• Cache de 1 hora: Gravação 2.0x + Leitura 0.1x = Após a primeira gravação, são necessários 2 acertos para se pagar (adicional pago de 1.0x, cada acerto economiza 0.9x)

Portanto, o cache de 5 minutos é quase sempre uma escolha "lucrativa", enquanto o cache de 1 hora exige garantir pelo menos 2 acertos dentro do período de validade.

Comparativo de Cobrança de Cache do Claude: Cache de 5 minutos vs 1 hora

Diferença de Preço entre Cache de 5 Minutos e 1 Hora

Abaixo, usando cada modelo como exemplo, listamos os preços específicos de escrita para cache de 5 minutos e 1 hora:

Estratégia de Escolha de TTL para Cobrança de Cache do Claude

Cache de 5 minutos e cache de 1 hora não são uma relação de escolha binária. Você pode escolher com flexibilidade de acordo com o cenário real, e até mesmo usá-los de forma mista na mesma requisição.

Cenários adequados para cache de 5 minutos:

• Chamadas de API de alta frequência (várias requisições por minuto), onde o cache é continuamente atualizado dentro de 5 minutos
• Cenários de diálogo interativo, onde o usuário envia mensagens continuamente, renovando automaticamente o cache
• Projetos sensíveis a custos, onde o custo de escrita é menor

Cenários adequados para cache de 1 hora:

• Tarefas de processamento em lote, onde um lote de dados pode ser executado apenas a cada dezenas de minutos
• System Prompt grande, com alto custo de escrita, onde se deseja que o cache sobreviva por mais tempo
• Cenários de tarefas agendadas, executadas a cada 15-30 minutos

Mecanismo importante: O cache de 5 minutos renova automaticamente o TTL (Tempo de Vida) sempre que é acessado, o que equivale a uma "renovação". Portanto, se a frequência das suas chamadas for suficientemente alta (pelo menos uma requisição a cada 5 minutos), o cache pode, na verdade, permanecer ativo indefinidamente, sem a necessidade de escolher o cache de 1 hora.

🎯 Recomendação técnica: Na maioria dos cenários, o cache de 5 minutos já é suficiente. Ao chamar a API do Claude através da plataforma APIYI apiyi.com, as regras de cobrança de cache são totalmente consistentes com as oficiais, e suporta o gerenciamento unificado de estratégias de cache para múltiplos modelos através de uma interface única.

Uso Misto de TTL na Cobrança de Cache do Claude

A Anthropic permite o uso simultâneo de dois controles de cache (1 hora e 5 minutos) na mesma requisição, mas há uma restrição crucial:

Ordenação do TTL do maior para o menor: A marcação de cache de 1 hora deve aparecer antes da marcação de cache de 5 minutos.

Na aplicação prática, você pode definir o System Prompt, que tem baixa frequência de alteração, como cache de 1 hora, e os exemplos Few-shot, que têm frequência de alteração um pouco maior, como cache de 5 minutos:

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com"  # Chamada via APIYI
)

response = client.messages.create(
    model="claude-sonnet-4-6-20260320",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Você é um assistente profissional de documentação técnica...(grande quantidade de texto do system prompt)...",
            "cache_control": {"type": "ephemeral", "ttl": "3600"}  # Cache de 1 hora
        }
    ],
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "A seguir está o documento de referência...(grande contexto)...",
                    "cache_control": {"type": "ephemeral"}  # Cache padrão de 5 minutos
                },
                {
                    "type": "text",
                    "text": "Com base no documento acima, responda: o que é Prompt Caching?"
                }
            ]
        }
    ]
)

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com"
)

response = client.messages.create(
    model="claude-sonnet-4-6-20260320",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Seu conteúdo de system prompt (precisa ter >= 1024 tokens para acionar o cache)",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "Olá"}]
)

# Verificar o uso do cache
usage = response.usage
print(f"Tokens de entrada: {usage.input_tokens}")
print(f"Tokens de escrita no cache: {usage.cache_creation_input_tokens}")
print(f"Tokens de leitura do cache: {usage.cache_read_input_tokens}")

# Determinar o status do cache
if usage.cache_read_input_tokens > 0:
    print("Cache acertado! Economizou 90% do custo de entrada")
elif usage.cache_creation_input_tokens > 0:
    print("Primeira escrita no cache, requisições subsequentes acertarão o cache")

💡 Atenção: Existe um requisito mínimo de tokens para o cache. O Claude Opus 4.6 requer pelo menos 1024 tokens, o Sonnet 4.6 e o Haiku 4.5 também requerem pelo menos 1024 tokens. Conteúdo abaixo desse limite não será armazenado em cache.

Mecanismo de Isolamento de Cache entre Contas no Claude

Esta é uma das maiores preocupações dos desenvolvedores: O cache gravado pela conta A pode ser acessado pela conta B?

Regras Fundamentais de Isolamento de Cache no Claude

A resposta é clara: Não. O cache é completamente isolado entre diferentes organizações (Organizations).

A partir de 5 de fevereiro de 2026, a Anthropic refinou ainda mais a granularidade do isolamento de cache, passando do nível "Organização" para o nível "Workspace". Isso significa:

Impacto Prático do Isolamento de Cache do Claude

Análise de Cenário: Suponha que você tenha duas contas da API Claude (pertencentes a Organizations diferentes) executando simultaneamente um lote de tarefas de processamento de dados.

• A conta A envia uma requisição, aciona a gravação no cache e paga a taxa de 1.25x para gravar
• A conta B envia exatamente o mesmo prompt dentro de 5 minutos
• Resultado: A conta B não acertará o cache da conta A. A conta B também acionará uma gravação no cache e pagará novamente 1.25x

Este é um design baseado em considerações de segurança e privacidade – o conteúdo do cache pode conter System Prompts sensíveis ou dados comerciais, e o compartilhamento entre organizações representaria um risco de vazamento de dados.

Estratégia de Otimização: Se você precisa que vários serviços compartilhem o cache para reduzir custos, deve colocar suas chaves API no mesmo Workspace, em vez de usar contas de Organizations diferentes.

🎯 Recomendação Prática: Na plataforma APIYI apiyi.com, as requisições de cada usuário são processadas através de um canal upstream unificado. Se você precisa compartilhar o cache entre múltiplos projetos, é recomendável planejar a estrutura de Workspaces no Anthropic Console de forma adequada, colocando os projetos que precisam compartilhar cache dentro do mesmo Workspace.

Condições para Acerto de Cache no Claude

Além do isolamento por Workspace, há uma condição crucial para o acerto de cache – o prompt deve ser 100% idêntico.

A chave de cache (Cache Key) é gerada através de um hash criptográfico do conteúdo do prompt. A correspondência inclui:

• tools (definições de ferramentas)
• system (comando do sistema)
• messages (histórico de mensagens)

Essas três partes são concatenadas em ordem, até a posição marcada por cache_control. Se qualquer caractere for diferente (incluindo espaços, quebras de linha), o cache não será acertado.

Comparação de Cobrança de Cache do Claude: AWS Bedrock vs Anthropic Oficial

Diferenças na Cobrança de Cache entre AWS Bedrock e a API Oficial da Anthropic

Muitas empresas usam o Claude através do AWS Bedrock, e a cobrança pelo cache apresenta as seguintes diferenças em relação à API oficial da Anthropic:

Principais Diferenças na Cobrança de Cache do Claude no AWS Bedrock

Diferença 1: Suporte a modelos para cache de 1 hora

Até janeiro de 2026, o AWS Bedrock oferece suporte a TTL de cache de 1 hora apenas para Claude Haiku 4.5, Sonnet 4.5 e Opus 4.5. Os modelos mais recentes, Opus 4.6 e Sonnet 4.6, podem ainda não ter a opção de cache de 1 hora disponível no Bedrock. Se você precisa da combinação do modelo mais recente + cache de 1 hora, recomenda-se usar a API oficial da Anthropic diretamente.

Diferença 2: Granularidade do isolamento do cache

O AWS Bedrock mantém o isolamento do cache no nível da Organization (ou seja, nível da AWS Account), enquanto a API oficial da Anthropic já refinou isso para o nível de Workspace. Isso significa que, no Bedrock, todas as chamadas sob a mesma conta AWS podem compartilhar o cache, uma granularidade mais grossa do que na API oficial.

Diferença 3: Variação de preço regional

Os endpoints regionais do AWS Bedrock (como us-east-1, eu-west-1) podem ter um prêmio de preço de cerca de 10% em relação ao endpoint global. Esse prêmio também se reflete nos custos de escrita e leitura do cache.

💰 Recomendação de Otimização de Custos: Se você usa principalmente a API do Claude e tem necessidades de controle refinado sobre a estratégia de cache, chamar a API nativa da Anthropic através do APIYI (apiyi.com) é uma opção mais flexível. A plataforma suporta a passagem completa de parâmetros de controle de cache e oferece preços mais vantajosos.

Perguntas Frequentes

Resumo

Os pontos principais da cobrança de cache da API Claude:

1. Cache de 5 minutos com multiplicador de 1,25x, cache de 1 hora com 2,0x: Para a maioria dos cenários, o cache de 5 minutos é suficiente. Em chamadas de alta frequência, o cache é renovado automaticamente, oferecendo efeito equivalente ao cache de longo prazo.
2. Leitura do cache custa apenas 0,1x: Ao acertar o cache, você economiza 90% do custo de entrada. O cache de 5 minutos se paga com apenas 1 acerto.
3. Isolamento do cache no nível do Workspace: Caches não são compartilhados entre diferentes organizações ou Workspaces. É necessário planejar a estrutura do Workspace adequadamente.

Para desenvolvedores que precisam fazer muitas chamadas à API Claude, o uso estratégico do cache pode reduzir custos significativamente. Recomendamos usar a plataforma APIYI apiyi.com para chamadas à API Claude, que suporta a passagem completa de parâmetros de cache, gerenciamento unificado de interfaces e oferece créditos de teste gratuitos para ajudar a validar a eficácia da estratégia de cache.

Referências

1. Documentação oficial do Anthropic Prompt Caching: Explicação completa do recurso de cache da API Claude.

   • Link: platform.claude.com/docs/en/build-with-claude/prompt-caching
   • Descrição: Inclui parâmetros essenciais como multiplicadores de preço, configuração de TTL e requisitos mínimos de tokens.

2. Página de preços da API Anthropic: Preços mais recentes de todos os modelos Claude.

   • Link: platform.claude.com/docs/en/about-claude/pricing
   • Descrição: Inclui preços básicos de entrada/saída e detalhes de preços para operações de cache.

3. Documentação do AWS Bedrock Prompt Caching: Guia de uso do cache Claude na plataforma AWS.

   • Link: docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
   • Descrição: Métodos de configuração de cache específicos do Bedrock e lista de modelos suportados.

4. Anúncio do cache de 1 hora do AWS Bedrock: Nota de lançamento do recurso de cache com TTL de 1 hora.

   • Link: aws.amazon.com/about-aws/whats-new/2026/01/amazon-bedrock-one-hour-duration-prompt-caching/
   • Descrição: Escopo de modelos e modo de uso do cache de 1 hora suportado pelo Bedrock.

Autor: Equipe Técnica da APIYI
Discussão técnica: Convidamos você a discutir questões relacionadas à cobrança de cache do Claude nos comentários. Para mais dicas de uso de API, visite o centro de documentação da APIYI em docs.apiyi.com.