Campos de Custo nas Respostas
Nesta página
Acompanhe Custos em Tempo Real
Cada resposta da API do Grok inclui os detalhes do custo imediato. Muitas equipas descobrem esta informação tarde demais, quando chega a fatura mensal, embora esteja disponível pedido a pedido. Ao aproveitar estes dados desde o início da integração, deteta desvios numa hora após a sua ocorrência: um prompt de sistema que duplicou de tamanho após uma implementação, um ciclo de repetição mal calibrado que repete as mesmas chamadas ou um contexto que ultrapassa um limiar de faturação. Sem este acompanhamento, estes incidentes permanecem invisíveis até à emissão do extrato.
O Objeto usage
Cada resposta inclui um objeto usage que detalha o consumo de tokens e o custo associado:
{
"usage": {
"prompt_tokens": 1250,
"completion_tokens": 340,
"total_tokens": 1590,
"cached_tokens": 800,
"cost_in_usd_ticks": 5000000000,
"cost_in_nano_usd": 500000000
}
}
Os quatro campos de contagem lêem-se da seguinte forma.
| Campo | Significado |
|---|---|
prompt_tokens | número de tokens de entrada (o seu prompt completo) |
completion_tokens | número de tokens de saída (a resposta do modelo) |
total_tokens | soma dos tokens de entrada e de saída |
cached_tokens | tokens de entrada servidos a partir da cache |
Um detalhe evita um erro comum: cached_tokens está incluído em prompt_tokens, não somado a este. No exemplo acima, 1.250 tokens entraram no modelo, 800 vieram da cache e apenas 450 foram faturados à taxa total. Se o seu agregador somar ambos os campos, contará em duplicado a parte em cache e inflacionará artificialmente as suas estatísticas de volume.
Duas Escalas para o Mesmo Custo
O custo do pedido é fornecido em duas unidades inteiras. Esta escolha não é arbitrária: expressar frações de cêntimo em números de ponto flutuante introduz erros de arredondamento que se tornam visíveis ao agregar milhões de chamadas. Os inteiros evitam totalmente este problema.
O campo cost_in_usd_ticks conta em “ticks”, com 10 mil milhões de ticks por dólar. O valor 5.000.000.000 no exemplo corresponde, portanto, a 0,50 $, e um milhão de ticks equivale a 0,0001 $. A conversão cabe numa linha:
cost_usd = cost_in_usd_ticks / 10_000_000_000
O campo cost_in_nano_usd conta em nanodólares, com mil milhões de nanodólares por dólar. Os 500.000.000 no exemplo representam o mesmo montante, 0,50 $, e mil nanodólares equivalem a 0,000001 $. A conversão segue a mesma lógica:
cost_usd = cost_in_nano_usd / 1_000_000_000
Ambos os campos descrevem o mesmo montante em escalas diferentes. cost_in_nano_usd é mais intuitivo de manusear, enquanto cost_in_usd_ticks oferece uma precisão ligeiramente superior. Escolha um e mantenha-o consistente em toda a sua cadeia de medição: misturar ambos na mesma agregação é a melhor forma de obter totais inconsistentes.
Construa um Rastreador de Custos
Em produção, um único acumulador é suficiente para transformar estes campos num painel de controlo. A classe abaixo regista cada objeto usage e expõe o custo cumulativo juntamente com a taxa de cache:
class CostTracker:
def __init__(self):
self.total_nano_usd = 0
self.requests = 0
self.input_tokens = 0
self.output_tokens = 0
self.cached_tokens = 0
def record(self, usage):
self.total_nano_usd += usage.get("cost_in_nano_usd", 0)
self.requests += 1
self.input_tokens += usage.get("prompt_tokens", 0)
self.output_tokens += usage.get("completion_tokens", 0)
self.cached_tokens += usage.get("cached_tokens", 0)
@property
def total_cost_usd(self):
return self.total_nano_usd / 1_000_000_000
@property
def cache_rate(self):
if self.input_tokens == 0:
return 0
return self.cached_tokens / self.input_tokens
De seguida, associe limiares a total_cost_usd. Um primeiro limiar a 80% do orçamento diário dispara um alerta informativo para a equipa técnica; um segundo a 95% torna-se um alerta crítico que exige decisão humana; aos 100%, a aplicação corta automaticamente os pedidos não críticos — trabalhos em lote, pré-cálculos, enriquecimentos diferidos — e permite apenas o tráfego direto do utilizador. Esta degradação graciosa é preferível a uma paragem súbita do serviço num dia de pico.
Analise a Taxa de Cache
A propriedade cache_rate merece um painel de controlo próprio, pois reflete diretamente a qualidade da estrutura do seu prompt.
| Taxa de Cache | Interpretação |
|---|---|
| 0 a 20% | sem cache eficaz, reveja a estrutura do prompt |
| 20 a 50% | cache parcial, verifique a estabilidade dos seus prompts de sistema |
| 50 a 80% | boa taxa para conversas |
| 80% ou mais | excelente, típico para prompts longos e estáveis |
Uma taxa que cai abruptamente de uma semana para a outra é quase sempre sinal de uma implementação que introduziu uma variável no início do prompt. A próxima lição detalha o mecanismo; por agora, lembre-se de que este valor é um indicador de regressão tão valioso quanto uma taxa de erro.
Preços a partir de 5 de agosto de 2026 — os preços evoluem regularmente: antes de qualquer cálculo orçamental, consulte a tabela de preços atual na página oficial de modelos e preços da xAI.
Pontos-chave
- Cada resposta da API contém um objeto
usagecom detalhes de tokens e custo cost_in_usd_ticks: 10 mil milhões de ticks = 1 USDcost_in_nano_usd: 1 mil milhão de nano-USD = 1 USD- O campo
cached_tokensmede a eficiência da cache - Construa um rastreador de custos em produção com alertas de orçamento