Tokens

Escopo: transversal. Aplica-se a qualquer linguagem ou stack do projeto.

Token é a unidade mínima de texto que um modelo de linguagem processa. Entender tokens é essencial para estimar custo, respeitar limites de contexto e otimizar prompts. A maioria das APIs cobra por token, não por caractere ou palavra.

O tokenizador divide o texto em pedaços baseado em padrões de frequência aprendidos no treinamento. Uma regra prática:

Palavras comuns em inglês costumam ser 1 token. Palavras longas ou raras podem ser divididas em múltiplos tokens. Espaços em branco e pontuação são tokens separados.

"Hello, world!"  →  ["Hello", ",", " world", "!"]  → 4 tokens
"Olá, mundo!"   →  ["Ol", "á", ",", " mundo", "!"] → 5 tokens

Para estimar com precisão, use o tokenizador do provedor: tiktoken (OpenAI), anthropic-tokenizer (Anthropic).

A context window define o limite de entrada por chamada. A saída máxima é um limite separado, definido pelo modelo. Se a entrada usar 900.000 tokens em um modelo com janela de 1.000.000, restam apenas 100.000 tokens disponíveis para saída, independente do limite máximo do modelo.

Contexto longo é útil, mas não gratuito: mais tokens de entrada significa maior custo e, em alguns modelos, aumento de latência.

A maioria das APIs cobra separadamente por input e output. Output tokens costumam ser 3-5x mais caros que input tokens.

Os valores abaixo são aproximados e podem mudar a qualquer momento. Sempre confira a tabela oficial do provedor antes de estimar custos em produção.

Preços de referência: Anthropic · OpenAI · Google

Para estimar o custo de uma chamada: (input_tokens × preço_input + output_tokens × preço_output) / 1_000_000.

O cache de prompts reutiliza tokens de entrada que não mudaram entre chamadas. O prefixo do prompt (system prompt, documentos de contexto, exemplos) é processado uma vez e armazenado em cache pelo provedor.

Primeira chamada:  processa 10.000 tokens → cobra preço normal
Chamadas seguintes: apenas os tokens novos (ex: mensagem do usuário) são processados → 90% de desconto

Anthropic: cache explícito via cache_control. Mínimo de 1.024 tokens para ser elegível ao cache.

{
  "system": [
    {
      "type": "text",
      "text": "Você é um assistente especializado em...",
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

OpenAI: cache automático, sem marcação explícita no payload (corpo da mensagem).

O cache tem TTL (Time To Live, tempo de vida) de aproximadamente 5 minutos para prompts com variação frequente.

Colocar o conteúdo estável no início do prompt. O cache funciona por prefixo: o system prompt e os documentos fixos devem vir antes das mensagens do usuário. Qualquer alteração no prefixo invalida o cache.

Usar o modelo certo para cada tarefa. Haiku 4.5 custa 5x menos que Sonnet 4.6 por token de saída. Tarefas simples (classificação, extração, resumo curto) não precisam do modelo mais capaz.

Combinar Prompt Caching com Batch API. A Batch API (Application Programming Interface, Interface de Programação de Aplicações) acumula o desconto do cache (90%) com o desconto do Batch (50%). Para processamento de documentos em volume, a redução de custo pode chegar a 95%.

Evitar output tokens desnecessários. Instruir o modelo a responder de forma concisa quando a tarefa permite. Output tokens são os mais caros.

Desenvolvido por @thiagocajadev · Fork baseado no repositório pmndrs/docs · Poimandres.