Claude Code gastando muito? Como otimizar o consumo de tokens na prática e não falir usando a API

A primeira vez que vi a fatura do Claude, confesso que me deu um frio na espinha. Era para ser uma automação "simples": pegar dados de umas 500 linhas de uma Google Sheet, fazer um resumo rápido de cada uma e categorizar. Algo que, se eu fosse fazer na mão, levaria uns dois dias chatos e repetitivos. Pensei: "Vou jogar no Claude, ele resolve em minutos e a conta vai ser irrisória". Que nada. Quando vi o consumo de tokens, a tal 'irrisória' virou um valor que me fez questionar se valia a pena continuar. A automação funcionou, sim, mas o preço foi maior do que o esperado. Foi aí que percebi que não bastava saber mandar um prompt; eu precisava aprender a economizar. E economizar de verdade, na prática, sem cair em papo furado de "otimização estratégica".

A real é que a API do Claude, com seus modelos potentes como Opus, Sonnet e até o Haiku, é uma mão na roda para muita coisa – desde gerar textos complexos até extrair insights de montanhas de dados. Mas o poder vem com um custo por token. Se você não cuidar, a conta chega pesada. Passei uns bons meses apanhando, testando, errando e refatorando código (em Python e Apps Script, que são minhas ferramentas do dia a dia) para chegar num ponto onde minhas automações com IA são eficientes e, o mais importante, financeiramente viáveis. E é sobre essa experiência, os perrengues e as soluções que encontrei, que vou falar aqui.

Entendendo o Custo: Como o Claude Conta os Tokens (e Onde a Grana Vai Embora)

Antes de otimizar, a gente precisa entender o inimigo (ou amigo caro, no caso). Tokens são as "unidades de medida" da IA. Não são palavras, são pedaços de palavras, ou até caracteres, dependendo do modelo e da língua. O importante é saber que a conta é feita em duas frentes:

Tokens de Input: Tudo que você manda para a API. Seu prompt, as instruções, o contexto, os dados que você quer que a IA processe. Pensa como a matéria-prima que você está fornecendo.
Tokens de Output: Tudo que a IA te devolve. A resposta, o resumo, a categoria, o código gerado. É o produto final.

O pulo do gato é que o custo por token de output é, geralmente, bem mais caro que o de input. Então, além de ser esperto no que você pede, tem que ser cirúrgico no que você quer receber. No começo, eu não dava bola para isso. Mandava prompts gigantescos com um monte de texto que a IA nem precisava ler, e ainda pedia respostas elaboradas demais. O resultado? Conta salgada. Aprendi na marra que cada token conta, tanto na entrada quanto na saída.

Otimização de Prompts: Meu Primeiro Campo de Batalha

A primeira coisa que aprendi a ajustar foi o prompt. Parece óbvio, mas muita gente erra aqui. Eu mesmo errei bastante.

Seja Direto e Específico – Menos Enrolação, Mais Economia

Quantas vezes a gente não se pega escrevendo um prompt que parece um e-mail formal para a IA? "Olá, Claude, espero que esteja bem. Poderia, por gentileza, analisar o texto abaixo e me fornecer um resumo detalhado dos principais pontos, considerando o contexto de vendas, por favor?". Isso é um festival de tokens desnecessários. A IA não precisa de preâmbulo, nem de cordialidade. Ela precisa de instrução clara e concisa.

Meu "antes": "Preciso que você leia este longo e-mail de um cliente e me diga os principais problemas que ele está enfrentando, mas de uma forma bem completa, incluindo detalhes relevantes." (Resultado: Prompt longo, resposta potencialmente longa).

Meu "depois": "Analise o e-mail do cliente abaixo. Liste os 3 problemas principais. Seja conciso." (Resultado: Prompt curto, resposta focada e curta).

Eu fui testando e percebi que a IA é literal. Se eu pedia "um breve resumo", vinha algo de 5 parágrafos. Mas se eu especificava "resumo em uma frase" ou "em no máximo 50 palavras", ela se virava para entregar aquilo. Essa clareza no que se espera, limitando a "criatividade" da IA, já corta um monte de tokens de output que você nem precisava.

Instruções Claras, Formatos Estruturados – Evitando 'Achismos' da IA

Outra coisa que me ajudou muito foi pedir a resposta em formatos específicos. Se eu preciso de dados para jogar numa Sheet ou num banco de dados, não quero um texto corrido. Quero JSON, CSV, ou uma lista bem estruturada.

Meu "antes": "Me diga as categorias dos produtos nesta lista." (Resultado: Uma frase bonitinha, "Os produtos são da categoria X, Y e Z", que eu tinha que parsear na mão com regex ou outro script).

Meu "depois": "Liste as categorias dos produtos. Formato: JSON com uma chave 'categorias' contendo um array de strings." (Resultado: {"categorias": ["Eletrônicos", "Alimentos", "Limpeza"]}. Direto ao ponto, fácil de parsear, e sem tokens extras de prosa).

Isso não só economiza tokens (porque a IA não precisa "inventar" uma frase para te dar a resposta), mas também economiza meu tempo de processamento depois. Menos código pra eu escrever, menos chance de erro. É uma vitória dupla.

Pré-processamento de Dados: A Chave que Virei no Python e Apps Script

Aqui, a coisa fica mais técnica. A maior parte do custo de tokens de input vem dos dados que a gente manda para a IA. Se você joga um documento inteiro de 10 páginas para resumir uma ideia de 3 linhas, está jogando dinheiro fora. A IA tem um limite de contexto enorme, mas isso não significa que você deve usá-lo todo sem pensar.

Filtragem e Resumo Antes do Prompt – O Segredo para Reduzir o Contexto

Eu lembro de uma vez que precisava analisar comentários de clientes que estavam em uma Google Sheet gigante. Cada linha tinha o comentário completo, a nota do cliente, o produto comprado, etc. No início, eu pegava o comentário inteiro (às vezes textos enormes) e mandava para o Claude para ele extrair os pontos negativos e positivos. A conta subia rápido demais. Depois, percebi que para muitos casos, só a nota, uma menção específica a 'entrega' ou 'produto', e talvez as 2-3 primeiras frases do comentário já bastavam para a IA ter contexto.

No Apps Script, eu comecei a fazer coisas como:

function processSheetComments() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Comentários");
  var data = sheet.getDataRange().getValues();

  for (var i = 1; i < data.length; i++) { // Ignora o cabeçalho
    var fullComment = data[i][2]; // Coluna do comentário
    var product = data[i][1]; // Coluna do produto

    // Pegar só as primeiras 200 palavras, por exemplo, ou fazer um filtro mais inteligente
    var relevantText = fullComment.split(' ').slice(0, 200).join(' '); 

    // Adiciona o produto ao contexto para a IA, mas não o comentário inteiro
    var prompt = `Análise o seguinte feedback sobre o produto '${product}': ${relevantText}. Quais são as principais dores do cliente em 1 frase?`;

    // ... chamar a API do Claude com este prompt mais curto ...
  }
}

No Python, com Pandas, isso fica ainda mais fácil. Se eu estivesse processando um CSV ou um DataFrame:

import pandas as pd

# Supondo que 'df' é o seu DataFrame
df['comentario_reduzido'] = df['comentario_completo'].apply(lambda x: ' '.join(x.split(' ')[:200]))

for index, row in df.iterrows():
    product = row['produto']
    relevant_comment = row['comentario_reduzido']
    
    prompt = f"Analise o seguinte feedback sobre o produto '{product}': {relevant_comment}. Quais são as principais dores do cliente em 1 frase?"
    
    # ... chamar a API do Claude com este prompt mais curto ...

Um simples regex ou um `string.contains` no Apps Script ou Python para extrair frases chave antes de montar o prompt salvou uma grana. Eu parei de alimentar a IA com dados que ela nem precisava processar para me dar a resposta que eu queria. É como ir a um restaurante e pedir para o chef ler o livro inteiro de culinária antes de fazer seu prato; ele só precisa da receita.

Chunking Inteligente: Quebrando Textos Grandes sem Perder o Sentido

Às vezes, não tem jeito: o texto é grande e você precisa que a IA processe boa parte dele. Um relatório de 10 páginas, por exemplo. Mandar tudo de uma vez para o Claude é caro, e em alguns casos pode até exceder os limites do modelo. A solução é o chunking, ou seja, quebrar o texto em pedaços menores.

Mas não basta quebrar de qualquer jeito. Dividir um texto a cada 1000 caracteres pode cortar uma frase no meio ou separar parágrafos que são contextualmente dependentes. Isso causa perda de sentido e a IA pode te dar respostas ruins. Meu aprendizado foi que o chunking precisa ser "inteligente".

Eu comecei a usar estratégias como:

Divisão por Parágrafos ou Seções: Se o texto tem uma estrutura clara (títulos, parágrafos), use isso. Cada parágrafo é um chunk.
Overlap de Chunks: Para não perder contexto entre os pedaços, faça com que cada chunk comece com as últimas 2-3 frases do chunk anterior. Isso dá uma "memória" para a IA sobre o que foi dito antes.
Resumo Iterativo: Mande chunk 1 para a IA e peça um resumo. Mande chunk 2 junto com o resumo do chunk 1, e peça um novo resumo que incorpore os dois. Repita. No final, você terá um resumo final do documento inteiro.

Um exemplo prático: para um relatório longo em Python, eu usaria algo assim (simplificado):

def split_text_into_chunks(text, max_chunk_size=2000, overlap_size=200):
    chunks = []
    current_pos = 0
    while current_pos < len(text):
        end_pos = min(current_pos + max_chunk_size, len(text))
        chunk = text[current_pos:end_pos]
        chunks.append(chunk)
        current_pos += max_chunk_size - overlap_size
        if current_pos >= len(text): # Evita loop infinito se o overlap for muito grande ou o texto for pequeno
            break
    return chunks

# ... então, processar cada chunk e possivelmente usar o resumo iterativo.
# Para cada chunk, você poderia enviar um prompt como:
# "Aqui está um resumo prévio do documento: [resumo_anterior]. Agora, processe este novo trecho: [chunk_atual]. Me dê um resumo atualizado que inclua os pontos importantes de ambos."

Dividir um relatório de 10 páginas em blocos de 1 página e processar cada um com um prompt focado é a diferença entre uma conta de centenas de dólares e uma de dezenas. O desafio é não perder o contexto entre os chunks, por isso, às vezes, um pequeno overlap ou um prompt de "contextualização" para o próximo chunk é necessário, como no exemplo acima. Dá um pouco mais de trabalho no código, mas o bolso agradece.

Otimizando as Respostas da IA: Controlando o Output para Não Estourar o Orçamento

Como mencionei antes, tokens de output são mais caros. Então, ter controle sobre o que a IA retorna é crucial.

Limitando o `max_tokens` – Impondo um Teto no Gasto

Essa é uma configuração básica da API, mas que eu demorei para dar a devida atenção. O parâmetro max_tokens (ou similar, dependendo da biblioteca que você usa) define o número máximo de tokens que a IA pode gerar na resposta. Se você sabe que precisa de uma resposta curta, defina esse limite!

Se eu peço um resumo em uma frase, não faz sentido deixar o max_tokens em 1000. Defina para 50, talvez 100 para ter uma margem. Se a IA atingir esse limite, ela vai parar de gerar texto, mesmo que a resposta não esteja "completa". Isso é um trade-off, claro. Você pode truncar uma informação importante se o limite for muito baixo. A chave é testar. Comece com um valor baixo e aumente gradualmente até a qualidade da resposta ser aceitável. Eu já perdi horas testando isso, ajustando max_tokens de 20 em 20, para achar o ponto ideal.

Em Python, usando a biblioteca do Anthropic, seria algo assim:

import anthropic

client = anthropic.Anthropic(api_key="SUA_CHAVE_AQUI")

response = client.messages.create(
    model="claude-3-opus-20240229",
    max_tokens=100, # Limita a resposta a 100 tokens
    messages=[
        {"role": "user", "content": "Me dê um resumo de uma página de um documento complexo. Qual o ponto principal?"}
    ]
)
print(response.content)

No Apps Script, usando `UrlFetchApp` para chamar a API diretamente:

function callClaudeWithMaxTokens(promptText) {
  var apiKey = "SUA_CHAVE_AQUI";
  var url = "https://api.anthropic.com/v1/messages";

  var headers = {
    "x-api-key": apiKey,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
  };

  var payload = {
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 75, // Limita a resposta a 75 tokens
    "messages": [
      {"role": "user", "content": promptText}
    ]
  };

  var options = {
    "method": "post",
    "headers": headers,
    "payload": JSON.stringify(payload)
  };

  var response = UrlFetchApp.fetch(url, options);
  var jsonResponse = JSON.parse(response.getContentText());
  return jsonResponse.content[0].text;
}

Prompt Engineering para Saídas Concisas – A Arte de Pedir Pouco e Receber o Essencial

Além do max_tokens, você pode (e deve) usar o próprio prompt para forçar a IA a ser concisa. Eu aprendi que quanto mais específico eu era no que esperava, menos a IA "viajava".

"Gere uma lista com no máximo 5 itens."
"Use no máximo 50 palavras."
"Responda com 'Sim' ou 'Não' e uma explicação breve de 10 palavras."
"Extraia apenas o nome do produto e o preço. Não adicione contexto."

Essa combinação de `max_tokens` com instruções claras no prompt é um combo poderoso. Fui testando e percebi que a IA é literal. Se eu pedia "um breve resumo", vinha algo de 5 parágrafos. Mas se eu especificava "resumo em uma frase", ela se virava. É um exercício de disciplina na escrita do prompt.

Batch Processing e Paralelização (Com Cuidado!)

Isso não diminui a quantidade de tokens por requisição, mas otimiza o tempo e a eficiência geral. Se você tem 1000 itens para processar, mandar um por um pode levar horas. Paralelizar, ou seja, mandar várias requisições ao mesmo tempo, acelera o processo. Isso pode não reduzir o custo total de tokens, mas dilui o "custo por item" no tempo, tornando a automação mais viável operacionalmente.

No Python, uso `concurrent.futures` ou `asyncio` para fazer várias chamadas à API simultaneamente. Isso é especialmente útil quando cada item precisa de um prompt individual, mas o processamento de um item é independente do outro.

from concurrent.futures import ThreadPoolExecutor
import anthropic

def process_single_item(item_data):
    client = anthropic.Anthropic(api_key="SUA_CHAVE_AQUI")
    prompt = f"Analise: {item_data}. Qual a categoria?"
    response = client.messages.create(
        model="claude-3-haiku-20240307", # Haiku é bom para tarefas rápidas e baratas
        max_tokens=20,
        messages=[{"role": "user", "content": prompt}]
    )
    return item_data, response.content[0].text

items_to_process = ["Dados do item 1", "Dados do item 2", "Dados do item 3", ...]
results = []

# Processa 10 itens em paralelo
with ThreadPoolExecutor(max_workers=10) as executor:
    for item, result in executor.map(process_single_item, items_to_process):
        results.append({"item": item, "categoria": result})

print(results)

No Apps Script, a paralelização é mais limitada e exige umas gambiarras com `UrlFetchApp` e `MimeType.JSON` ou fazendo chamadas assíncronas em um loop, mas tem limites de concorrência e tempo de execução. Geralmente, para grandes volumes, eu prefiro Python por ser mais robusto para isso.

O cuidado aqui é não sobrecarregar a API (você pode ser rate-limited) e não processar itens que não precisam de IA (lembra do pré-processamento?). É uma otimização de tempo, que indiretamente ajuda a justificar o custo dos tokens.

Comparativo: Jeito Manual/Demorado vs. Jeito Automatizado e Otimizado

Para deixar mais claro o que eu quero dizer, montei essa tabela com um cenário de análise de feedback de clientes.

Aspecto	Jeito Manual/Demorado (e Caro)	Jeito Automatizado (e Econômico)
Objetivo	Resumir feedback de 500 clientes sobre produtos.	Extrair pontos-chave (negativos/positivos) e categoria de sentimento (Positivo/Neutro/Negativo) para 500 feedbacks.
Dados de Entrada (Prompt)	Enviar o comentário completo (ex: 500 palavras) + nome do produto + data para o Claude.	Pré-processar no Python/Apps Script: filtrar para pegar apenas as 3-5 frases mais relevantes do comentário (ex: 100 palavras) + nome do produto.
Instrução no Prompt	"Me dê um resumo detalhado deste feedback de cliente, destacando os pontos positivos e negativos."	"Análise o feedback abaixo (produto: [NomeProduto]). Identifique o principal ponto NEGATIVO e o principal ponto POSITIVO. Classifique o sentimento geral (Positivo, Neutro, Negativo). Formato JSON: {'negativo': 'texto', 'positivo': 'texto', 'sentimento': 'string'}."
Controle de Output	Não usar `max_tokens` ou usar um valor muito alto (ex: 1000).	Definir `max_tokens` (ex: 150), ajustado para o JSON esperado.
Processamento	Um a um, sem paralelização. Cada resposta com texto corrido, difícil de usar.	Paralelização em Python com `ThreadPoolExecutor`, com output em JSON fácil de injetar em Sheets/DB.
Custo Estimado por Item	Alto (ex: 200 tokens input + 150 tokens output = 350 tokens).	Baixo (ex: 100 tokens input + 50 tokens output = 150 tokens).
Custo Total para 500 Itens	Bem caro e demorado.	Substancialmente mais barato e muito mais rápido.

O Que Dá Errado: Armadilhas e Perrengues Reais

Nem tudo são flores na otimização. Passei por algumas situações chatas que me ensinaram lições importantes:

Truncagem Inesperada: Definir max_tokens baixo demais. Eu estava pedindo para resumir um relatório de desempenho em 30 tokens. A IA, coitada, tentava, mas cortava no meio da frase mais importante. O resumo ficava inútil. Levei um tempo para entender que é preciso um equilíbrio entre economia e utilidade. Às vezes, 50 tokens extras valem a pena para ter a informação completa.
Perda de Contexto com Chunking: Quebrar textos grandes de forma arbitrária (por número de caracteres, por exemplo) é um tiro no pé. A IA lê um pedaço, depois outro, mas como as informações estavam soltas, as respostas ficavam sem pé nem cabeça. Perdi um dia inteiro refazendo a lógica de chunking porque o primeiro resultado parecia que a IA tinha tido um derrame. O overlap e o resumo iterativo são mais complexos de implementar, mas essenciais para textos realmente grandes.
Micro-otimização Excessiva: Já me peguei otimizando um prompt por 30 minutos para economizar 10 tokens. É frustrante. Em um projeto pequeno, onde as chamadas são poucas, o custo de tempo do desenvolvedor (eu, no caso) otimizando para economizar centavos de dólar não vale a pena. É preciso ter um senso de escala: onde a economia faz uma diferença real na fatura?
Ignorar Custo de Latência: Múltiplas chamadas para a API com prompts super otimizados podem ser mais baratas em tokens, mas o tempo de espera total (latência de rede + processamento da IA para cada chamada) pode aumentar muito. Se você precisa de uma resposta rápida, às vezes é melhor mandar um pouco mais de tokens e fazer uma chamada só, do que fragmentar demais e esperar por 10 respostas pequenas.
Não Validar Saída: Assumir que a IA entendeu a otimização de prompt e entregou o esperado sem verificar os primeiros resultados é um erro. Sempre confira algumas saídas para garantir que a concisão não comprometeu a qualidade da informação. Já gastei dinheiro processando 500 linhas com um prompt otimizado, para só depois perceber que a IA estava ignorando uma instrução crucial de formatação. O resultado? Tive que refazer tudo.
Caching Simples (e não usar): Se você já processou um dado e obteve uma resposta da IA, por que processar de novo? Para dados estáticos ou que mudam pouco, implemente um sistema de cache. Pode ser tão simples quanto salvar o resultado numa coluna extra da Google Sheet ou num arquivo JSON local. Essa é a economia mais "na cara" e que eu demorei para levar a sério. Eu me vi processando os mesmos dados repetidamente, sem necessidade. Agora, antes de chamar a API, sempre verifico se aquele item já foi processado e salvo.

FAQ: Perguntas de Quem Está na Batalha Diária

1. Devo sempre buscar o menor número de tokens possível, mesmo que a resposta da IA fique um pouco "truncada"?

Não, nem sempre. É um equilíbrio. Se a informação truncada perde valor para o seu objetivo, a economia de tokens pode se tornar um desperdício, pois você terá que refazer ou complementar manualmente. Busque a concisão que mantém a utilidade. Otimize até o ponto em que a qualidade da resposta continua servindo ao seu propósito. Menos tokens é bom, mas não à custa da irrelevância.

2. A otimização de prompt (estrutura, concisão) muda com versões diferentes do Claude (Opus, Sonnet, Haiku)?

As bases da otimização (seja direto, use formato estruturado, limite saída) valem para todos. No entanto, modelos mais potentes como Opus podem entender prompts mais complexos e ambíguos melhor do que Haiku, por exemplo. Isso significa que, com o Haiku (mais barato), você talvez precise ser ainda mais explícito e detalhista nas suas instruções para garantir a saída desejada, compensando sua menor capacidade de "raciocínio". Com Opus, você pode ter um pouco mais de folga, mas o custo é maior, então a disciplina ainda é crucial. É uma questão de ajustar o nível de rigor do prompt ao modelo escolhido.

3. Como posso medir os tokens de forma precisa antes de enviar para a API, para ter uma estimativa de custo?

A Anthropic, como outras empresas de IA, oferece APIs ou bibliotecas de tokenização para calcular o número de tokens de um texto antes de enviá-lo para a API principal. Isso é super útil para pré-calcular custos. Em Python, você pode usar a função de tokenização da própria biblioteca do Anthropic ou de outras como `tiktoken` para modelos OpenAI (embora a tokenização seja diferente para Claude). No Apps Script, seria necessário fazer uma chamada para um endpoint de tokenização (se disponível e documentado pela Anthropic, ou criar sua própria estimativa baseada em experimentos, que é menos precisa). Na prática, eu geralmente mando um lote pequeno de dados de teste, vejo o consumo real no dashboard da Anthropic e escalo a partir daí.

Conclusão

Olhar para a fatura da API do Claude e não ter um susto é um luxo que poucos têm sem um trabalho ativo de otimização. O que aprendi na prática é que não existe bala de prata. É uma combinação de pré-processamento inteligente dos dados, prompts cirúrgicos, controle rígido do output e, sim, um pouco de malabarismo no código com Python ou Apps Script para automatizar tudo. Não é um bicho de sete cabeças, mas exige disciplina e muita tentativa e erro. Eu já passei horas refatorando prompts, ajustando limites de tokens, reescrevendo funções de chunking. É chato, é frustrante, mas no fim do mês, quando a fatura vem mais amigável, a gente percebe que valeu a pena. A IA é uma ferramenta poderosa, mas como qualquer ferramenta cara, precisa ser usada com sabedoria, ou o martelo vira marreta no seu bolso.

A Mente Vetorial

Pesquisar este blog