Claude Sonnet 4.5 com ferramentas: calcule o custo de uma tarefa, não apenas de uma chamada

O custo de uma chamada não é o custo de uma tarefa

Uma integração pode apresentar apenas uma solicitação do usuário e, ainda assim, enviar várias solicitações ao Claude antes de concluir o trabalho. O modelo pode propor o uso de uma ferramenta; a aplicação executa essa operação e devolve o resultado; em seguida, o modelo processa o contexto novamente e decide se responde ou se precisa de outra ferramenta. Para estimar o gasto da tarefa, conte cada solicitação ao modelo — não apenas a solicitação inicial ou a resposta final.

Este guia propõe uma planilha para o Claude Sonnet 4.5. Ela separa tokens de entrada, tokens de saída e eventuais cobranças de ferramentas hospedadas no servidor. Não inclui cache nem a Batch API. Também não pressupõe que todas as tarefas tenham o mesmo número de rodadas: uma pesquisa simples, um fluxo com várias etapas e uma tentativa malsucedida podem ter custos diferentes.

O cálculo se refere ao uso da API do Claude em um fluxo delimitado, no qual a aplicação executa ferramentas. Não o aplique automaticamente ao Bedrock, ao Google Cloud ou a outra plataforma: podem existir identificadores, tarifas, unidades de cobrança ou cronogramas diferentes. Para consultar o guia de preços, use a rota interna pricing.index; para o modelo, Claude Sonnet 4.5; e para o fornecedor, Anthropic.

Defina o modelo, o canal e o identificador antes de estimar

O nome comercial não basta para reproduzir um cálculo. Para a Claude API, a documentação de identificadores diferencia o alias claude-sonnet-4-5 da versão datada claude-sonnet-4-5-20250929. A página sobre o ciclo de vida identifica essa versão como ativa e informa que ela não será retirada antes de 29 de setembro de 2026. Essa é uma referência útil, não uma garantia de disponibilidade futura: confira o estado do modelo antes de publicar ou reutilizar a planilha.

Registre também o canal. As páginas da Anthropic descrevem identificadores equivalentes para outros provedores, mas não se deve presumir que o mesmo preço, cronograma ou formato de uso se aplique a todos eles. A tarifa inserida na planilha deve corresponder ao canal efetivamente usado e à data da execução. A documentação de preços é a referência para verificar as tarifas vigentes, possíveis diferenças regionais e condições de plataformas associadas.

O material de verificação fornecido não inclui os valores atuais das tarifas de entrada e saída nem o valor de eventuais diferenças regionais; por isso, eles não são apresentados aqui como dados confirmados. A planilha mantém essas tarifas como campos editáveis. Antes de transformar o resultado em orçamento, substitua-os pelos valores indicados na documentação aplicável e anote a data da consulta.

Conte uma rodada completa do ciclo de ferramentas

No uso de ferramentas do lado do cliente, uma resposta do modelo pode conter uma solicitação para usar uma ferramenta. A aplicação executa a ação e envia o resultado da ferramenta em uma mensagem posterior; então, o modelo processa a continuação. Essa troca pode se repetir. A mensagem que solicita o uso da ferramenta não equivale a uma tarefa concluída.

Para cada solicitação ao modelo, conte a entrada realmente enviada naquela solicitação. Ela pode incluir a mensagem de sistema, mensagens anteriores, definições de ferramentas, a mensagem do usuário e resultados anteriores que a aplicação tenha mantido no contexto. Se uma nova solicitação incluir novamente conteúdo anterior, esse conteúdo volta a fazer parte do cálculo de entrada daquela solicitação. Não conte o resultado da ferramenta como entrada do modelo até que ele seja efetivamente enviado.

A saída também é contabilizada por solicitação. Em uma rodada intermediária, ela pode consistir em uma instrução para a ferramenta e seus argumentos; na última, em uma resposta destinada ao usuário. Não presuma que uma saída intermediária tenha custo zero. Para o Claude Sonnet 4.5, o uso de ferramentas pode acrescentar tokens de sistema associados à ferramenta escolhida. A quantidade depende da configuração; consulte a documentação de preços para verificá-la. Não some um valor genérico sem confirmar qual ferramenta e modalidade estão em uso.

Uma ferramenta hospedada no servidor exige uma separação adicional. Suas operações podem ter cobranças próprias, e alguns ciclos podem ser executados internamente no serviço. Nesse caso, nem sempre cada operação interna equivale a uma chamada visível para o cliente. Mantenha separados o contador de solicitações ao modelo e o contador de operações da ferramenta; fature cada conceito de acordo com a unidade documentada.

Modelo de cálculo por rodada e por tarefa

Organize a planilha com uma linha por solicitação ao modelo e outra tabela, ou um bloco separado, para as cobranças das ferramentas. Em cada linha do modelo, anote os tokens de entrada faturáveis, os tokens de saída faturáveis e os preços de entrada e saída, todos correspondentes ao canal e à data registrados. Se houver uma ferramenta hospedada, registre também cada operação cobrada por ela. Assim, é possível somar o gasto de uma tarefa sem misturar unidades.

A estimativa de tokens de cada chamada é: (tokens de entrada ÷ unidade da tarifa) × preço de entrada + (tokens de saída ÷ unidade da tarifa) × preço de saída. A unidade da tarifa deve ser a publicada pelo fornecedor; se o preço for por milhão de tokens, a unidade será um milhão. Para obter o custo de uma tarefa, some os resultados de todas as chamadas ao modelo e acrescente, separadamente, as cobranças aplicáveis das ferramentas.

A soma das entradas não deve eliminar teoricamente conteúdo repetido. Se uma mensagem de sistema, um esquema de ferramenta ou um resultado anterior aparecer em três solicitações faturáveis, conte o uso registrado em cada solicitação, mesmo que o texto seja idêntico. Por outro lado, não acrescente tokens estimados para conteúdo que não foi enviado. Quando não houver medidas confiáveis, identifique o valor como estimativa e compare-o com a ferramenta de contagem de tokens ou com os dados de uso retornados pela API.

Três cenários ilustrativos

Os cenários a seguir mostram como estruturar a contagem; não preveem um padrão universal de uso. Os volumes de tokens são exemplos para testar a planilha, não medições do Claude nem preços publicados. Para obter um custo monetário real, substitua os tokens ilustrativos pelos registros da sua aplicação e pelos preços verificados para o seu canal.

Cenário A: uma consulta respondida sem ferramentas. Conte a única solicitação ao modelo, incluindo as mensagens e o contexto enviados, e a saída gerada. Se a aplicação incluir uma definição de ferramenta mesmo sem usá-la, confira o conteúdo efetivo da solicitação; não presuma que essa definição foi gratuita ou que não estava presente. Há apenas uma rodada do modelo neste caso, mas isso não significa que todas as consultas do produto tenham o mesmo custo.

Cenário B: uma pergunta que exige uma pesquisa. Conte a primeira chamada, a resposta que solicita a ferramenta, a operação de pesquisa e a chamada posterior que inclui o resultado. Se for usada uma ferramenta hospedada no servidor, registre a cobrança na unidade indicada pela documentação; não a converta em tokens. Se a aplicação integrar uma pesquisa externa do lado do cliente, registre a despesa externa correspondente fora da fatura de tokens do Claude.

Cenário C: uma ação com várias chamadas sequenciais ou uma tentativa malsucedida. Se a primeira ferramenta retornar um erro e a aplicação pedir ao modelo que o corrija, some essa chamada e as seguintes. Se o processo for reiniciado como uma nova tentativa, mantenha o identificador da tentativa e some o consumo dela ao custo da tarefa concluída. Informar apenas a tentativa bem-sucedida ocultaria o gasto necessário para alcançar o resultado.

Quais variáveis podem alterar o resultado

O número de rodadas costuma ser uma variável decisiva. Uma tarefa concluída após a primeira resposta pode exigir menos chamadas do que outra que dependa de três decisões do modelo. Mas não atribua toda diferença ao modelo: ela pode depender da lógica da aplicação, do estado da ferramenta, da qualidade dos dados, do limite de novas tentativas ou do critério de sucesso.

O contexto mantido pelo cliente também influencia o resultado. O envio de definições extensas, mensagens anteriores e resultados volumosos pode aumentar a entrada de rodadas posteriores. Reduzir o histórico pode alterar o consumo, mas só é correto se as informações necessárias para a tarefa forem mantidas. Meça o efeito em uma execução controlada, em vez de presumir que o contexto será resumido ou cobrado apenas uma vez.

Os esquemas das ferramentas e os tokens de sistema associados acrescentam outra variável. A quantidade específica depende da ferramenta e da configuração; portanto, deve ser conferida na documentação de preços e na contagem da solicitação. Um resultado longo de ferramenta também pode aumentar a entrada da chamada seguinte, desde que seja enviado ao modelo.

Por fim, separe tarefas malsucedidas, novas tentativas automáticas e correções solicitadas pelo usuário. Um orçamento baseado na média das tarefas concluídas pode subestimar o gasto se omitir tentativas malsucedidas. É recomendável apresentar tanto o custo por tentativa quanto o custo agregado por tarefa concluída, junto com o período e o conjunto de execuções medido.

Compare a planilha com a produção e declare as exclusões

Para uma auditoria, mantenha um identificador de tarefa e de tentativa, o identificador do modelo, o canal, o número de cada solicitação, as ferramentas disponíveis, os resultados enviados ao modelo e os dados de uso de cada resposta. Registre também chamadas malsucedidas e operações que não produziram uma resposta útil. Evite armazenar dados pessoais ou segredos desnecessários para a análise; as métricas de custo podem ser associadas a identificadores internos pseudonimizados.

A documentação da API inclui um endpoint de contagem de tokens que aceita mensagens, instruções de sistema e ferramentas. Ele pode ajudar a estimar uma solicitação antes do envio. Não substitui a comparação com os dados de uso retornados durante a execução nem com a fatura final, especialmente quando há várias rodadas, erros ou cobranças de ferramentas. Use a estimativa prévia para planejar e os registros efetivos para auditar.

Compare o custo calculado com a fatura em um período e canal equivalentes. Investigue discrepâncias procurando chamadas ausentes, unidades de tarifa interpretadas incorretamente, diferenças regionais ou cobranças separadas de ferramentas. Mantenha uma coluna para exclusões explícitas. Neste cálculo, cache e Batch API ficam de fora; podem exigir tratamentos próprios e não devem ser inseridos na fórmula como se fizessem parte do fluxo básico.

Um valor útil não é necessariamente uma previsão exata. Publique o método, a data dos preços, o conjunto de tarefas, o número de tentativas e as exclusões. Se a amostra tiver pouca variedade, apresente-a como resultado daquela amostra, e não como custo típico de qualquer tarefa com o Sonnet 4.5.

Continue a explorar

Correções e transparência

Se encontrar informação incorreta ou desatualizada, envie-nos a página e a fonte que devemos rever.