Skip to main content
Toda resposta de LLM carrega um objeto usage que informa os tokens que a requisição consumiu. Sunra informa o uso na semântica do endpoint que você chamou: uma resposta Messages segue o contrato Anthropic, e uma resposta Chat Completions ou Responses segue o contrato OpenAI. Esses formatos diferem, deliberadamente. Um SDK OpenAI lendo uma resposta Chat Completions assume a semântica OpenAI, e um SDK Anthropic lendo uma resposta Messages assume a semântica Anthropic. Cada endpoint honra o que sua própria especificação promete, em vez de ser forçado a um formato único compartilhado.
/v1/messages e /v1/responses usam ambos o nome de campo input_tokens, e ele não significa a mesma coisa nos dois. Em Messages, é apenas a entrada nova. Em Responses, é o prompt inteiro, tokens em cache incluídos.

​
Messages

Em /v1/messages, os três buckets de entrada são mutuamente exclusivos. Nenhum token é contado duas vezes, então o total do prompt é a soma deles:
​
integer
Apenas os tokens de entrada novos. Exclui ambos os buckets de cache.
​
integer
Tokens escritos no cache por esta requisição.
​
integer
Tokens servidos a esta requisição a partir do cache.
​
integer
Tokens gerados pelo modelo.
​
integer
Os três buckets de entrada mais output_tokens. Presente em respostas não-streaming.
Um bucket ausente ou null conta como zero.

​
Exemplo prático

O mesmo prefixo de 19.000 tokens enviado duas vezes contra claude-opus-4-8. A primeira requisição escreve o cache; a segunda o lê.
Requisição fria (escrita no cache)
Requisição quente (leitura do cache)
input_tokens permanece em 8 nas duas requisições, porque 8 é a entrada genuinamente nova em cada uma. O prefixo de 19.349 tokens passa do bucket de criação para o bucket de leitura. Ambas as requisições somam os mesmos 19.359 tokens no total, mas não custam o mesmo: escritas de cache e leituras de cache são precificadas com suas próprias taxas por token, e é por isso que são reportadas como buckets separados.

​
Chat Completions e Responses

Esses endpoints reportam a semântica OpenAI, inalterada. A contagem do prompt é o prompt inteiro, e os tokens em cache são um subconjunto dele, reportado separadamente.
/v1/chat/completions
Somar prompt_tokens e cached_tokens conta em duplicidade. Para obter a entrada nova nesses endpoints, subtraia:
A mesma regra se aplica a /v1/responses com input_tokens e input_tokens_details.cached_tokens.

​
O marcador sunra_usage_semantics

Respostas que Sunra normalizou carregam um marcador dentro de usage:
O marcador é uma promessa sobre a resposta, não sobre qualquer evento ou campo individual. Em uma resposta não-streaming ele aparece no objeto usage raiz; em uma resposta com streaming ele aparece em message_start, o evento que carrega os buckets de entrada. Quando ele está presente com este valor, as garantias desta página valem: os três buckets de entrada são mutuamente exclusivos, e total_tokens — quando presente — é a soma deles mais output_tokens. A ausência dele também é uma promessa. Sunra normaliza apenas os formatos de resposta que mediu. Qualquer outro é encaminhado do provedor upstream intocado e deixado sem marcação, e uma resposta sem o marcador é uma resposta cujos buckets Sunra não garante. Verifique o marcador em vez de inspecionar os números para adivinhar qual convenção uma resposta segue. Farejar o formato é exatamente o que este campo existe para substituir — uma heurística como “os buckets devem ser exclusivos porque somam mais do que a contagem do prompt” é satisfeita por mais de uma convenção e mais cedo ou mais tarde lerá uma resposta de forma errada.
Apenas respostas de /v1/messages carregam o marcador. Chat Completions e Responses seguem a especificação OpenAI e não são marcadas. O valor é versionado. Uma mudança incompatível no significado desses campos é publicada sob um novo valor, então uma verificação de igualdade contra anthropic.exclusive.v1 não começará silenciosamente a ler um contrato diferente.

​
Streaming

Em uma requisição Messages com streaming, o uso chega em dois eventos. message_start carrega o lado da entrada e o marcador. O message_delta final carrega apenas output_tokens. Verifique o marcador em message_start e então faça a fusão usual dos dois eventos — aplicar o uso do evento posterior sobre o anterior — para chegar aos valores documentados acima. total_tokens é omitido em respostas com streaming. Nenhum evento isolado conhece tanto o lado da entrada quanto o da saída, então qualquer total calculado no meio do stream estaria errado. Some os buckets você mesmo depois que o stream terminar.

​
Migrando do comportamento anterior

Sunra anteriormente encaminhava o objeto usage upstream literalmente em /v1/messages. A camada de tradução na frente de alguns provedores dobra os tokens de criação de cache dentro de input_tokens, então quem seguia o contrato Anthropic e somava os três buckets contava os tokens de criação de cache duas vezes.
  • Se você soma os três buckets, como o contrato Anthropic descreve, você agora está correto. Nenhuma mudança é necessária do seu lado.
  • Se você compensava o comportamento antigo — subtraindo cache_creation_input_tokens de input_tokens você mesmo, ou de outra forma fazendo engenharia reversa da dobra — pare. Essa correção agora subtrai tokens que já estavam excluídos e vai subestimar sua entrada.
  • Se você lê total_tokens, ele continua reportando a contagem completa: entrada nova, ambos os buckets de cache e saída.
Condicione a mudança ao marcador em vez de a uma data de deploy, para que o mesmo caminho de código esteja correto tanto com respostas marcadas quanto não marcadas.