Cache de Prompt do Claude

Documentation Index

Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt

Use this file to discover all available pages before exploring further.

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [Place complete text content here]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

Como funciona o cache de prompt

1. O sistema verifica se um prefixo de prompt, até um ponto de quebra de cache especificado, já está cacheado de uma consulta recente.
2. Se encontrado, ele usa a versão cacheada, reduzindo o tempo de processamento e os custos.
3. Caso contrário, processa o prompt completo e cacheia o prefixo assim que a resposta começa. Isso é especialmente útil para:

• Prompts com muitos exemplos
• Grandes quantidades de contexto ou informações de background
• Tarefas repetitivas com instruções consistentes
• Conversas longas com múltiplos turnos

​

Preços

• Tokens de escrita de cache de 5 minutos são 1,25 vezes o preço base dos tokens de entrada
• Tokens de escrita de cache de 1 hora são 2 vezes o preço base dos tokens de entrada
• Tokens de leitura de cache são 0,1 vezes o preço base dos tokens de entrada
• Tokens regulares de entrada e saída são cobrados às taxas padrão da plataforma

​

Como implementar o cache de prompt

​

Modelos suportados

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

Estruturando seu prompt

​

Limitações do cache

• 1024 tokens para Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 e Claude Opus 3
• 2048 tokens para Claude Haiku 3.5 e Claude Haiku 3

• “ephemeral”: Vida útil padrão de 5 minutos
• Cache de 1 hora (Beta): Para cenários que requerem duração de cache mais longa

​

Duração de cache de 1 hora (Beta)

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​

Quando usar cache de 1 hora

• Processamento em lote: Processar grandes volumes de requisições com prefixos comuns
• Sessões de longa duração: Conversas que requerem manutenção de contexto por períodos prolongados
• Análise de documentos grandes: Múltiplos tipos diferentes de análise no mesmo documento
• Q&A em codebase: Múltiplas consultas no mesmo codebase por períodos prolongados

​

Misturando diferentes TTLs

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​

O que pode ser cacheado

• Ferramentas: Definições de ferramentas no array tools
• Mensagens de sistema: Blocos de conteúdo no array system
• Mensagens: Blocos de conteúdo no array messages.content, tanto para turnos de usuário quanto de assistente
• Imagens & Documentos: Blocos de conteúdo no array messages.content, em turnos de usuário
• Uso de ferramentas e resultados de ferramentas: Blocos de conteúdo no array messages.content, em turnos de usuário e assistente

​

O que não pode ser cacheado

• Blocos de thinking não podem ser cacheados diretamente com cache_control. Não entanto, blocos de thinking PODEM ser cacheados junto com outro conteúdo quando aparecem em turnos anteriores de assistente. Quando cacheados desta forma, eles CONTAM como tokens de entrada quando lidos do cache.
• Sub-blocos de conteúdo (como citações) por si só não podem ser cacheados diretamente. Em vez disso, cacheie o bloco de nível superior.
• Blocos de texto vazios não podem ser cacheados.

​

Rastreando desempenho do cache

• cache_creation_input_tokens: Número de tokens escritos no cache ao criar uma nova entrada.
• cache_read_input_tokens: Número de tokens recuperados do cache para esta requisição.
• input_tokens: Número de tokens de entrada que não foram lidos do cache nem usados para criar um cache.

​

Melhores práticas para cache eficaz

• Cacheie conteúdo estável e reutilizável como instruções de sistema, informações de background, contextos grandes ou definições frequentes de ferramentas.
• Coloque o conteúdo cacheado no início do prompt para melhor desempenho.
• Use pontos de quebra de cache estrategicamente para separar diferentes seções de prefixo cacheáveis.
• Analise regularmente as taxas de acerto do cache e ajuste sua estratégia conforme necessário.
• Para conteúdo de longo prazo, considere usar cache de 1 hora para melhor eficiência de custo.

​

Otimizando para diferentes casos de uso

• Agentes conversacionais: Reduza custo e latência para conversas estendidas, especialmente aquelas com instruções longas ou documentos enviados.
• Assistentes de codificação: Melhore o autocompletar e Q&A em codebase mantendo seções relevantes ou uma versão resumida do codebase no prompt.
• Processamento de documentos grandes: Incorpore material longo completo incluindo imagens em seu prompt sem aumentar a latência de resposta.
• Conjuntos de instruções detalhadas: Compartilhe listas extensivas de instruções, procedimentos e exemplos para ajustar finamente as respostas do Claude. Desenvolvedores frequentemente incluem um exemplo ou dois no prompt, mas com cache de prompt você pode obter desempenho ainda melhor incluindo 20+ exemplos diversificados de respostas de alta qualidade.
• Uso agêntico de ferramentas: Aumente o desempenho para cenários envolvendo múltiplas chamadas de ferramentas e mudanças iterativas de código, onde cada etapa tipicamente requer uma nova chamada de API.
• Converse com livros, papers, documentação, transcrições de podcasts e outros conteúdos longos: Dê vida a qualquer base de conhecimento incorporando o(s) documento(s) inteiro(s) no prompt e deixando os usuários fazerem perguntas.

​

Solucionando problemas comuns

• Garanta que seções cacheadas sejam idênticas e marcadas com cache_control nos mesmos locais em todas as chamadas
• Verifique se as chamadas são feitas dentro da vida útil do cache (5 minutos ou 1 hora)
• Verifique que tool_choice e uso de imagem permanecem consistentes entre chamadas
• Valide que está cacheando pelo menos o número mínimo de tokens
• Embora o sistema tente usar conteúdo previamente cacheado em posições anteriores a um ponto de quebra de cache, você pode usar um parâmetro cache_control adicional para garantir a busca no cache em porções anteriores do prompt, o que pode ser útil para consultas com listas muito longas de blocos de conteúdo

​

Armazenamento e compartilhamento de cache

• Isolamento da Organização: Os caches são isolados entre organizações. Organizações diferentes nunca compartilham caches, mesmo se usarem prompts idênticos.
• Correspondência Exata: Acertos de cache requerem segmentos de prompt 100% idênticos, incluindo todo texto e imagens até e incluindo o bloco marcado com cache_control. O mesmo bloco deve ser marcado com cache_control durante as leituras e criação do cache.
• Geração de Tokens de Saída: O cache de prompt não tem efeito na geração de tokens de saída. A resposta que você recebe será idêntica ao que você obteria se o cache de prompt não fosse usado.

​

Suporte em Diferentes Modelos

• O suporte ao Cache de Prompt depende do próprio modelo.
• Se o modelo inerentemente suporta cache sem exigir declarações explícitas de parâmetros, pode ser suportado através de encaminhamento compatível com OpenAI.
• A OpenAI suporta Cache de Prompt por padrão. Prompts cacheados não são cobrados, a recuperação de tokens cacheados custa metade da taxa normal, e os caches são automaticamente limpos após 5-10 minutos de inatividade. Detalhes
• O Claude requer a declaração nativa cache_control: { type: "ephemeral" }. A taxa de cache é 1,25 vezes o custo padrão de entrada (5 minutos) ou 2 vezes (1 hora), a recuperação de tokens cacheados custa 0,1 vez a taxa normal, com ciclo de vida de 5 minutos ou 1 hora. Detalhes
• Deepseek V3 e R1 suportam cache nativamente. A taxa de cache é igual ao custo padrão de entrada, a recuperação de tokens cacheados custa 0,1 vez a taxa normal. Detalhes
• Suporte a cache implícito do Gemini:
  • Cache Implícito: Habilitado por padrão para todos os modelos Gemini 2.5. Se sua requisição acertar o cache, as economias de custo são aplicadas automaticamente. Esse recurso é efetivo a partir de 8 de maio de 2025. A contagem mínima de tokens de entrada para cache de contexto é 1.024 para Gemini 2.5 Flash e 2.048 para Gemini 2.5 Pro.
  • Dicas para melhorar a taxa de acerto do cache implícito:
    • Tente colocar conteúdo grande e frequentemente reutilizado no início do prompt.
    • Tente enviar requisições com prefixos similares dentro de uma janela curta de tempo.
  • Você pode visualizar o número de tokens com acerto de cache no campo usage_metadata do objeto de resposta.
  • As economias de custo são calculadas com base nos acertos do cache de prefill. Apenas o cache de prefill e o cache de pré-processamento de vídeos do YouTube são elegíveis para cache implícito.