Claude Sonnet 5 foi lançado em 30 de junho de 2026 e é o modelo Sonnet mais "agentic" que a Anthropic já lançou. Ele tem um desempenho próximo ao do Opus 4.8 em tarefas de uso de ferramentas e codificação, a um preço muito mais baixo, o que o torna uma opção padrão forte para qualquer coisa que chame ferramentas em um loop. Este guia mostra como chamar a API do Claude Sonnet 5 de ponta a ponta: obter uma chave, enviar sua primeira solicitação em curl e Python, ler a resposta, lidar com o novo padrão de pensamento adaptativo, evitar as três alterações de solicitação que retornam erros 400, transmitir saídas longas e contar tokens com o novo tokenizador.
Você também configurará tudo no Apidog para que suas solicitações fiquem em uma coleção reutilizável com ambientes salvos e testes automatizados, em vez de espalhadas pelo histórico do shell. Se você já chamou a API Messages antes, a maior parte disso parecerá familiar. O ID do modelo é claude-sonnet-5, e o formato da solicitação corresponde ao que você já usa.
O que você precisa antes de começar
Você precisa de três coisas para chamar a API.
- Uma conta Anthropic e uma chave de API do console da plataforma Claude.
- O ID do modelo:
claude-sonnet-5. É a string exata, sem sufixo de data. - Uma forma de enviar requisições HTTP. curl funciona para um teste rápido. Apidog funciona melhor quando você está iterando.
Sonnet 5 está disponível para todos os clientes da API, além do Amazon Bedrock (através da Plataforma Claude na AWS), Google Cloud através do Vertex AI e Microsoft Foundry em pré-visualização. Este guia usa a API direta da Anthropic. O corpo da requisição é o mesmo em todas as plataformas; apenas a autenticação e o host do endpoint mudam.
Obtenha sua chave de API
Faça login no console da plataforma Claude, abra a seção de chaves de API e crie uma nova chave. Copie-a uma vez e guarde-a em um local seguro, pois o console não a exibirá novamente. Nunca codifique a chave diretamente no seu código-fonte ou a envie para o git. Em vez disso, defina-a como uma variável de ambiente:
export ANTHROPIC_API_KEY="sk-ant-..."
Se você possui um acordo ZDR, o Sonnet 5 suporta retenção zero de dados, então nada na superfície da API muda para você aqui.
Sua primeira requisição
A API do Sonnet 5 usa o endpoint Messages da Anthropic. Aqui está uma requisição mínima com curl.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Write a haiku about API testing."}
]
}'
A mesma requisição com o SDK Python:
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Write a haiku about API testing."}
],
)
print(message.content[0].text)
Dois campos fazem o trabalho pesado. model seleciona o Sonnet 5. max_tokens limita a saída total. Continue lendo, pois max_tokens se comporta de forma diferente no Sonnet 5 do que no Sonnet 4.6, e é o mais fácil de errar.
Lendo a resposta
Uma chamada bem-sucedida retorna HTTP 200 com um corpo JSON como este (reduzido):
{
"id": "msg_01ABC...",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5",
"content": [
{"type": "text", "text": "Assertions green,\nendpoints answer on the first try,\nship the merge tonight."}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 18,
"output_tokens": 27
}
}
Alguns campos são importantes para o trabalho real.
contenté um array. O texto reside em blocos ondetypeé"text". Com o uso de ferramentas ou o pensamento adaptativo habilitado, você verá outros tipos de blocos no mesmo array, então itere; não presuma quecontent[0]é sempre sua resposta.stop_reasoninforma por que a geração terminou.end_turné normal.max_tokenssignifica que você atingiu o limite e a saída foi truncada.refusalé novo e vale a pena entender (abaixo).usagereportainput_tokenseoutput_tokens. É isso que é cobrado, e os números são maiores no Sonnet 5 para o mesmo texto devido ao novo tokenizador.
O motivo de parada 'refusal'
Sonnet 5 é o primeiro modelo de nível Sonnet com salvaguardas de cibersegurança em tempo real. Se uma requisição abordar um tópico cibernético proibido ou de alto risco, o modelo pode recusar. Uma recusa retorna como um HTTP 200 normal com stop_reason: "refusal", não como um erro. Trate-o em seu código de análise de resposta da mesma forma que trataria qualquer motivo de parada que não seja end_turn, em vez de considerá-lo uma chamada HTTP falha.
O pensamento adaptativo está ativado por padrão
Esta é a maior mudança de comportamento em relação ao Sonnet 4.6, e confunde as pessoas. No Sonnet 4.6, a ausência do campo thinking significava que não havia pensamento. No Sonnet 5, o pensamento adaptativo está ativado por padrão. Uma requisição sem o campo thinking agora é executada com pensamento adaptativo, e os tokens de pensamento contam para sua saída total.
Como max_tokens é um limite rígido na saída total (tokens de pensamento mais texto de resposta), um valor de max_tokens que era confortável no 4.6 agora pode truncar sua resposta visível antes que ela termine. Se você migrou uma carga de trabalho que nunca usou o pensamento e definiu um max_tokens apertado, aumente-o ou espere truncamento.
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
thinking={"type": "disabled"},
messages=[
{"role": "user", "content": "Return only the JSON, no reasoning."}
],
)
Para manter o pensamento adaptativo ativado e controlar o quanto o modelo trabalha, use o parâmetro effort em vez de tentar definir um orçamento manual de tokens. O esforço suporta low, medium, high e xhigh. Um esforço maior significa um pensamento mais profundo e mais gasto de tokens. A Anthropic documenta o comportamento na página de pensamento adaptativo. Observe que o valor do campo é {"type": "adaptive"}, e não um número budget_tokens.
Três alterações de requisição que retornam 400
Se você está portando código do Sonnet 4.6 ou de um modelo Claude mais antigo, três coisas que costumavam funcionar agora retornam um erro 400. Corrija-as antes de migrar.
- Pensamento estendido manual foi removido.
thinking: {type: "enabled", budget_tokens: N}retorna 400. Já estava obsoleto no 4.6. Use o pensamento adaptativo mais o parâmetro de esforço em vez disso. - Parâmetros de amostragem são rejeitados. Definir
temperature,top_poutop_kpara um valor não padrão retorna 400. Remova-os. Omiti-los, ou deixá-los no padrão, está ok. Direcione o comportamento com instruções de prompt do sistema em vez disso. Essa restrição já existia no Opus 4.7 e superior; é nova para a classe Sonnet. - Pré-preenchimento de mensagens do assistente não é suportado. Pré-preencher o início da vez do assistente retorna 400. Use saídas estruturadas ou
output_config.formatou instruções de prompt do sistema para formatar a saída em vez disso.
Todo o resto que funciona no Sonnet 4.6 funciona no Sonnet 5 sem outras alterações de código. Os formatos de requisição, resposta e streaming são idênticos. Para um guia de migração mais completo, consulte nosso guia sobre a API Claude Sonnet 4.6, que aborda a mesma superfície de requisição que o Sonnet 5 herda.
Streaming para saídas grandes
Sonnet 5 suporta até 128.000 tokens de saída. Para respostas longas, ou qualquer requisição onde o pensamento adaptativo eleva a saída total, transmita o resultado para que você receba os tokens à medida que são gerados, em vez de esperar pela resposta completa. O streaming também evita timeouts do cliente em grandes gerações.
with client.messages.stream(
model="claude-sonnet-5",
max_tokens=8000,
messages=[
{"role": "user", "content": "Draft an OpenAPI 3.1 spec for a bookstore checkout API."}
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
O formato do evento de streaming é o mesmo do Sonnet 4.6, então os manipuladores de stream existentes funcionam sem alterações.
Contagem de tokens com o novo tokenizador
Sonnet 5 usa um novo tokenizador. O mesmo texto de entrada produz aproximadamente 30% mais tokens do que no Sonnet 4.6, cerca de 1.3x. Isso não é uma mudança na API. Os formatos de requisição, resposta e streaming são idênticos, e você não precisa mudar nenhum código por isso. Mas afeta tudo o que você mede ou orça em tokens.
- Seus números de
usagee resultados de contagem de tokens são maiores para o mesmo texto. Conte novamente com o Sonnet 5; não reutilize suas contagens do 4.6. - A janela de contexto de 1.000.000 de tokens comporta menos texto em média, porque cada token agora cobre menos texto.
- Um valor de
max_tokensdimensionado perto da sua saída esperada pode agora ser truncado. Revise-o. - O custo por requisição para texto equivalente pode ser maior, mesmo que o preço por token permaneça inalterado.
Use o endpoint de contagem de tokens antes de enviar, para que você esteja orçando com os números reais do Sonnet 5:
count = client.messages.count_tokens(
model="claude-sonnet-5",
messages=[
{"role": "user", "content": "Estimate the tokens for this prompt on Sonnet 5."}
],
)
print(count.input_tokens)
A Anthropic documenta isso na página de contagem de tokens.
Erros, limites de taxa e conceitos básicos de custo
Semânticas HTTP padrão se aplicam. Um 400 significa uma requisição malformada (as três mudanças acima são os suspeitos usuais no Sonnet 5). Um 401 significa uma chave de API inválida ou ausente. Um 429 significa que você atingiu um limite de taxa. Leia o cabeçalho retry-after e espere antes de tentar novamente. Lembre-se que uma recusa é um 200, não um erro, então não a direcione pela sua lógica de repetição.
Sobre precificação, a taxa introdutória é de US$ 2 por milhão de tokens de entrada e US$ 10 por milhão de tokens de saída, em vigor até 31 de agosto de 2026. Depois disso, ela passa para o padrão de US$ 3 por milhão de entrada e US$ 15 por milhão de saída, a mesma taxa por token do Sonnet 4.6. Devido à mudança do tokenizador, o custo de uma requisição de texto equivalente ainda pode ser maior do que no 4.6, mesmo que a taxa por token seja a mesma, então modele suas cargas de trabalho reais com contagem de tokens em vez de assumir paridade plana. Para uma análise de custo mais aprofundada, consulte nossa análise de custo da API Claude e o guia de limites de taxa da API Claude. O Nível de Prioridade não está disponível no Sonnet 5.
Teste e organize suas chamadas do Sonnet 5 no Apidog
Depois de passar do primeiro comando curl, você vai querer suas requisições salvas, sua chave armazenada uma única vez e suas respostas verificadas automaticamente. É aí que o Apidog se encaixa. É uma plataforma de API completa, então a mesma requisição que você envia manualmente se torna um recurso reutilizável e testável. Baixe o Apidog para acompanhar.
Aqui está uma configuração prática para a API do Sonnet 5.
1. Crie a requisição. Adicione uma nova requisição HTTP no Apidog. Defina o método como POST e a URL como https://api.anthropic.com/v1/messages. Adicione os cabeçalhos anthropic-version: 2023-06-01 e content-type: application/json. Cole o corpo JSON com "model": "claude-sonnet-5".
2. Armazene a chave de API como uma variável de ambiente. Crie um ambiente (por exemplo, “Produção Anthropic”) e adicione uma variável chamada ANTHROPIC_API_KEY. Referencie-a no cabeçalho x-api-key como {{ANTHROPIC_API_KEY}}. Agora sua chave reside em um só lugar, fora do corpo da sua requisição, e você pode trocar de ambientes sem editar as requisições.
3. Salve em uma coleção. Agrupe suas requisições do Sonnet 5, uma chamada de mensagem simples, uma chamada de streaming, uma chamada de ferramentas, em uma única coleção. Toda sua equipe terá as mesmas requisições testadas e aprovadas em vez de copiar trechos de curl por aí.
4. Adicione um teste automatizado. Anexe asserções à requisição para que uma execução falhe ruidosamente quando algo mudar. Por exemplo:
- Afirme que o status da resposta é
200. - Afirme que
modelé igual aclaude-sonnet-5. - Afirme que
stop_reasonestá presente e não émax_tokens(uma maneira rápida de detectar truncamento após a mudança do tokenizador). - Afirme que
usage.output_tokensé maior que0.
Encadeie estas em um cenário de teste e execute-o em CI sempre que mudar prompts ou migrar versões de modelo. Essa última asserção é a maneira mais barata de detectar uma regressão de max_tokens causada pelo pensamento adaptativo estar agora ativado por padrão.
5. Simule o endpoint. O mock inteligente do Apidog retorna uma resposta realista para o formato de Messages, para que o código cliente do seu aplicativo, o tratamento de erros e o parser de streaming possam ser construídos e testados sem gastar um único token. Isso é útil para trabalho de frontend e para testar a carga da sua própria camada de integração.
Se você está saindo do Postman para isso, nossa visão sobre testes de API sem Postman em 2026 aborda por que um fluxo de trabalho de design-mais-teste-mais-mock em uma única ferramenta economiza idas e vindas. Prefere o terminal? O guia completo da CLI do Apidog mostra como executar esses mesmos testes salvos em um pipeline.
Perguntas Frequentes
Qual é o ID do modelo Claude Sonnet 5?
É claude-sonnet-5, a string exata sem sufixo de data. Use-o no campo model da sua requisição Messages. É um substituto direto para claude-sonnet-4-6, então na maioria dos casos você muda o ID do modelo e revisa três coisas: o pensamento adaptativo agora ativado por padrão, os parâmetros de amostragem removidos e o orçamento de pensamento manual removido. Para uma visão completa do modelo, leia o que é o Claude Sonnet 5.
Por que a saída do meu max_tokens está sendo cortada no Sonnet 5?
O pensamento adaptativo está ativado por padrão, e os tokens de pensamento contam para o max_tokens junto com o texto da sua resposta. Se o seu limite foi ajustado para uma carga de trabalho sem pensamento no Sonnet 4.6, aumente-o, ou defina thinking: {"type": "disabled"} se você não quiser pensamento algum. O novo tokenizador produz cerca de 30% mais tokens para o mesmo texto, o que agrava o efeito.
Preciso mudar meu código para migrar do Sonnet 4.6?
Apenas em três lugares. Remova temperature, top_p e top_k não padrão. Remova qualquer thinking: {type: "enabled", budget_tokens: N}. Remova o pré-preenchimento de mensagens do assistente. Cada um desses retorna um 400 no Sonnet 5. Todo o resto, incluindo streaming e formatos de resposta, permanece inalterado. Se você também usa o Opus, nosso guia da API Opus 4.8 usa a mesma superfície de Messages.
Uma recusa é um erro que preciso capturar?
Não. Uma recusa de cibersegurança retorna HTTP 200 com stop_reason: "refusal". Trate-a como uma resposta normal com um motivo de parada diferente de end_turn, não como uma requisição falha. Não a envie pelo seu caminho de repetição em caso de erro.
Quanto custa a API do Sonnet 5?
A precificação introdutória é de US$ 2 por milhão de tokens de entrada e US$ 10 por milhão de tokens de saída até 31 de agosto de 2026, passando para US$ 3 e US$ 15 depois disso. A taxa por token corresponde ao Sonnet 4.6, mas o novo tokenizador significa que o texto equivalente pode custar mais, então meça com a contagem de tokens em vez de assumir paridade.