Calculadora de custo de API: tokens, cache e volume de requisições

Quais dados a calculadora precisa?

Para a API de texto, prepare sete entradas:

input_tokens_per_call
output_tokens_per_call
cache_write_tokens_per_miss
cache_read_tokens_per_hit
calls
cache_hit_rate
prices_per_1m_tokens

Quer comparar a previsão com uma chamada real? Crie uma conta BetterToken e uma API Key, use as tarifas atuais da página de preços e faça uma requisição controlada. Depois compare modelo, status, input, output, cache token aplicável e consumo no Dashboard para descobrir quais premissas devem ser corrigidas.

O caching varia por modelo e protocolo. Antes de preencher os campos, consulte a referência de API da BetterToken, OpenAI Prompt Caching ou Anthropic Prompt Caching.

Fórmula universal

Definições:

I  — tokens regulares de input
O  — tokens de output
W  — tokens de cache write / criação
R  — tokens de cache read / em cache
Pi — preço de input por 1.000.000 de tokens
Po — preço de output por 1.000.000 de tokens
Pw — preço de cache write por 1.000.000 de tokens
Pr — preço de cache read por 1.000.000 de tokens

Custo de uma chamada:

C = I / 1_000_000 × Pi
  + O / 1_000_000 × Po
  + W / 1_000_000 × Pw
  + R / 1_000_000 × Pr
  + Cextra

Cextra inclui unidades cobradas separadamente: busca na web, imagens, áudio, storage, tools ou outras operações. Se não existirem, o valor é zero. Se você não sabe se há cobrança adicional, deixe o campo desconhecido e consulte a documentação; zero criaria precisão falsa.

O maior erro manual é esquecer de dividir por um milhão. Quando o preço é por 1.000.000 de tokens, primeiro divida os tokens por 1_000_000 e só então multiplique pela tarifa.

Calculadora Python copiável

O script não contém preços nem API Key. Ele solicita as entradas e calcula um cenário. O resultado usa a mesma moeda das tarifas informadas.

from decimal import Decimal, InvalidOperation

MILLION = Decimal("1000000")

def read_decimal(label: str, *, allow_empty: bool = False) -> Decimal:
    raw = input(label).strip().replace(",", ".")
    if allow_empty and raw == "":
        return Decimal("0")
    try:
        value = Decimal(raw)
    except InvalidOperation as exc:
        raise SystemExit(f"Invalid number for {label!r}") from exc
    if value < 0:
        raise SystemExit(f"Negative value is not allowed for {label!r}")
    return value

input_tokens = read_decimal("Input tokens per call: ")
output_tokens = read_decimal("Output tokens per call: ")
cache_write_tokens = read_decimal("Cache write tokens per call: ")
cache_read_tokens = read_decimal("Cache read tokens per call: ")
calls = read_decimal("Number of calls: ")

price_input = read_decimal("Input price per 1M tokens: ")
price_output = read_decimal("Output price per 1M tokens: ")
price_cache_write = read_decimal("Cache write price per 1M tokens: ")
price_cache_read = read_decimal("Cache read price per 1M tokens: ")
extra_per_call = read_decimal("Extra cost per call (empty = 0): ", allow_empty=True)

per_call = (
    input_tokens / MILLION * price_input
    + output_tokens / MILLION * price_output
    + cache_write_tokens / MILLION * price_cache_write
    + cache_read_tokens / MILLION * price_cache_read
    + extra_per_call
)
total = per_call * calls

print(f"Cost per call: {per_call:.8f}")
print(f"Total cost:    {total:.8f}")
Mostrar mais

Salve como api_cost_calculator.py e execute:

python3 api_cost_calculator.py

Não informe tokens reais nos campos cache write/read se o endpoint atual não separar essas categorias. Primeiro converta o uso em grupos mutuamente exclusivos para não contar o mesmo token duas vezes.

Como considerar a taxa de cache hit

Em uma série de consultas, separe cache hits e misses:

N     — número total de chamadas
h     — taxa de cache hit de 0 a 1
Nhits — N × h
Nmiss — N - Nhits
Chit  — custo de uma chamada com cache read
Cmiss — custo de uma chamada sem hit ou com cache write

Resultado:

Ctotal = Nhits × Chit + Nmiss × Cmiss + Cextra_total

Para planejamento, arredonde Nhits para baixo e Nmiss para cima. Em logs reais, use a quantidade efetiva de chamadas de cada tipo.

Três cenários em vez de um número

Cenário básico

Use a mediana de input e output de tarefas recentes, o número esperado de chamadas e a taxa de cache hit observada. Se ainda não houver histórico, marque os valores como suposições.

Cenário favorável

Prefixo longo estável, alta taxa de cache hit, output limitado e sem erros repetidos. Ele mostra um limite inferior, mas não deve virar promessa de orçamento.

Pior caso

Inclua cache misses, output longo, um retry limitado e tools cobrados separadamente. Não aumente todos os parâmetros arbitrariamente: cada suposição deve corresponder a um risco real do processo.

Registre os resultados em uma planilha simples:

scenario, calls, hit_rate, input, output, write, read, extra, total
base,     ...,   ...,      ...,   ...,    ...,   ...,  ...,   ...
low,      ...,   ...,      ...,   ...,    ...,   ...,  ...,   ...
high,     ...,   ...,      ...,   ...,    ...,   ...,  ...,   ...

Como avaliar um workflow de agent

Uma execução visível de agent nem sempre equivale a uma chamada de modelo. Ela pode conter planejamento, tool call, tool result, retry e resposta final. Portanto:

1. faça uma tarefa de teste segura;
2. conte as chamadas de API reais;
3. agrupe-as por modelo e categoria de uso;
4. aplique a fórmula a cada grupo;
5. some separadamente unidades de tool ou busca;
6. compare o valor ao Dashboard.

Não multiplique o custo de uma chamada aleatória pelo número de usuários quando o tamanho das requisições variar muito. É melhor considerar classes de tarefas: pergunta curta, revisão de arquivo e tarefa de agent.

Como confrontar previsão e fato

Após a chamada de teste, confira:

• horário e request status;
• Model ID;
• tokens de input e output;
• categoria de cache;
• número de retries;
• consumo real;
• moeda e data da tarifa.

A diferença geralmente aponta para tarifa errada, contagem dupla de cached tokens, retry oculto ou transação adicional cobrável. Para BetterToken, use a página de preços atual e confira a entrada real do Dashboard; não copie preços de capturas ou artigos antigos.

Limitações da calculadora

A fórmula cobre apenas categorias conhecidas. Ela não prevê mudanças de tarifa, preços futuros, roteamento dinâmico nem número de etapas de agent. Imagem, áudio, busca web, storage e algumas tools podem ter unidades próprias.

Também não avalia a qualidade da resposta. Uma chamada mais barata que exija repetição manual pode aumentar o custo da tarefa inteira; isso é medido por experimento separado, não por um coeficiente inventado.

FAQ

O que informar se não há uso de cache?

Defina cache write e cache read como zero somente se o endpoint realmente não usou cache. Se o valor for desconhecido, confira primeiro o uso.

Em qual moeda sai o resultado?

O resultado usa a moeda das tarifas e de extra_per_call informadas. Não misture dólares e rublos sem taxa de câmbio explícita e data.

Cached tokens estão incluídos em input tokens?

Depende do formato de uso da API específica. Consulte a documentação e transforme os campos em categorias mutuamente exclusivas para evitar contagem dupla.

Como calcular o custo de um mês?

Calcule primeiro o custo de uma classe de tarefas e depois multiplique pelo número real ou previsto de chamadas. Use linhas separadas para modelos e tarefas diferentes, então some o total.

Por que a cobrança real é maior que a estimativa?

Verifique output, retries, etapas de agent, cache misses e tools adicionais. Relacione cada linha de uso ao Dashboard, e não apenas o total.