DEV Community

Cover image for Como Usar a API Claude Sonnet 5 (Passo a Passo com Apidog)
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Usar a API Claude Sonnet 5 (Passo a Passo com Apidog)

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 chega perto do Opus 4.8 em tarefas de uso de ferramentas e codificação, com custo menor, o que o torna uma boa opção padrão para fluxos que chamam ferramentas em loop. Neste guia, você vai chamar a API do Claude Sonnet 5 de ponta a ponta: criar uma chave, enviar requisições com curl e Python, interpretar a resposta, lidar com pensamento adaptativo, evitar erros 400 comuns, usar streaming e contar tokens com o novo tokenizador.

Experimente o Apidog hoje

Você também pode configurar tudo no Apidog para manter suas requisições em uma coleção reutilizável, com ambientes salvos e testes automatizados, em vez de depender do histórico do shell. Se você já usa a API Messages, o fluxo é familiar: o ID do modelo é claude-sonnet-5, e o formato da requisição segue o mesmo padrão.

O que você precisa antes de começar

Antes de chamar a API, prepare:

  • Uma conta Anthropic e uma chave de API do console da plataforma Claude.
  • O ID do modelo: claude-sonnet-5.
  • Um cliente HTTP, como curl, Python SDK ou Apidog.

image

Sonnet 5 está disponível para clientes da API, Amazon Bedrock por meio da Plataforma Claude na AWS, Google Cloud via Vertex AI e Microsoft Foundry em pré-visualização. Este guia usa a API direta da Anthropic. Em outras plataformas, o corpo da requisição é semelhante; autenticação e host mudam.

1. Obtenha sua chave de API

No console da plataforma Claude:

  1. Acesse a seção de chaves de API.
  2. Crie uma nova chave.
  3. Copie a chave uma vez e armazene-a com segurança.
  4. Não faça commit da chave no Git.

Defina a chave como variável de ambiente:

export ANTHROPIC_API_KEY="sk-ant-..."
Enter fullscreen mode Exit fullscreen mode

Se você possui um acordo ZDR, o Sonnet 5 suporta retenção zero de dados. A superfície da API não muda por causa disso.

Sua primeira requisição com curl

A API do Sonnet 5 usa o endpoint Messages da Anthropic.

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."}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Campos principais:

  • model: seleciona claude-sonnet-5.
  • max_tokens: limita a saída total.
  • messages: contém a conversa enviada ao modelo.

Atenção: no Sonnet 5, max_tokens também inclui tokens usados pelo pensamento adaptativo.

A mesma chamada com Python

Instale o SDK, se ainda não tiver:

pip install anthropic
Enter fullscreen mode Exit fullscreen mode

Envie a requisição:

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)
Enter fullscreen mode Exit fullscreen mode

Para código de produção, não assuma que content[0] sempre contém texto. Com ferramentas ou pensamento adaptativo, a resposta pode incluir múltiplos blocos.

Como ler a resposta

Uma resposta bem-sucedida retorna HTTP 200 com um corpo parecido com este:

{
  "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
  }
}
Enter fullscreen mode Exit fullscreen mode

Na prática, trate estes campos:

  • content: array de blocos. Extraia blocos com type == "text" para obter a resposta textual.
  • stop_reason: indica por que a geração terminou.
    • end_turn: conclusão normal.
    • max_tokens: saída truncada.
    • refusal: recusa de segurança.
  • usage: mostra input_tokens e output_tokens, usados para cobrança e monitoramento.

Exemplo simples para extrair texto com segurança:

texts = [
    block.text
    for block in message.content
    if block.type == "text"
]

print("\n".join(texts))
Enter fullscreen mode Exit fullscreen mode

Como tratar stop_reason: "refusal"

Sonnet 5 é o primeiro modelo de nível Sonnet com salvaguardas de cibersegurança em tempo real. Se a requisição abordar um tópico cibernético proibido ou de alto risco, o modelo pode recusar.

Essa recusa retorna:

  • HTTP 200
  • stop_reason: "refusal"

Ou seja, não trate como erro HTTP. Trate como uma resposta válida com motivo de parada diferente de end_turn.

Exemplo:

if message.stop_reason == "refusal":
    print("A requisição foi recusada pelo modelo.")
elif message.stop_reason == "max_tokens":
    print("A resposta foi truncada. Aumente max_tokens.")
elif message.stop_reason == "end_turn":
    print("Resposta concluída normalmente.")
Enter fullscreen mode Exit fullscreen mode

Pensamento adaptativo está ativado por padrão

Esta é a principal mudança em relação ao Sonnet 4.6.

No Sonnet 4.6, se você não enviava o campo thinking, o modelo não usava pensamento. No Sonnet 5, a ausência de thinking significa que o pensamento adaptativo está ativado por padrão.

Isso afeta max_tokens, porque o limite inclui:

  • tokens de pensamento
  • tokens visíveis da resposta

Se você migrar uma carga de trabalho do Sonnet 4.6 com max_tokens apertado, a resposta pode ser truncada.

Desativar pensamento adaptativo

Use isto quando quiser resposta direta, sem raciocínio adicional:

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    thinking={"type": "disabled"},
    messages=[
        {"role": "user", "content": "Return only the JSON, no reasoning."}
    ],
)
Enter fullscreen mode Exit fullscreen mode

Controlar esforço do pensamento adaptativo

Para manter pensamento adaptativo, use esforço em vez de orçamento manual de tokens.

Valores suportados:

  • low
  • medium
  • high
  • xhigh

Um esforço maior tende a consumir mais tokens. A Anthropic documenta esse comportamento na página de pensamento adaptativo.

O campo usa o formato:

{
  "type": "adaptive"
}
Enter fullscreen mode Exit fullscreen mode

Não use budget_tokens com Sonnet 5.

Três mudanças que causam erro 400

Ao migrar do Sonnet 4.6 ou de modelos Claude mais antigos, revise estes pontos.

1. Remova pensamento estendido manual

Este formato retorna 400:

{
  "thinking": {
    "type": "enabled",
    "budget_tokens": 4096
  }
}
Enter fullscreen mode Exit fullscreen mode

Use pensamento adaptativo com esforço ou desative thinking.

2. Remova parâmetros de amostragem não padrão

Estes parâmetros retornam 400 quando definidos com valores não padrão:

{
  "temperature": 0.2,
  "top_p": 0.9,
  "top_k": 40
}
Enter fullscreen mode Exit fullscreen mode

Remova-os. Para controlar comportamento, use instruções no system prompt ou no prompt do usuário.

3. Remova pré-preenchimento de mensagens do assistente

Pré-preencher o início da resposta do assistente não é suportado no Sonnet 5 e retorna 400.

Em vez disso, use:

  • instruções de formatação no prompt
  • saídas estruturadas
  • output_config.format, quando aplicável

A maior parte do restante da API Messages continua igual ao Sonnet 4.6. Para uma referência de migração, veja o guia da API Claude Sonnet 4.6.

Streaming para saídas grandes

Sonnet 5 suporta até 128.000 tokens de saída. Para respostas longas, use streaming para receber tokens conforme são gerados e reduzir risco de timeout no cliente.

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)
Enter fullscreen mode Exit fullscreen mode

O formato de streaming é o mesmo do Sonnet 4.6, então handlers existentes continuam funcionando.

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 muda o formato da API, mas muda planejamento e custo.

Impactos práticos:

  • usage.input_tokens e usage.output_tokens podem aumentar para o mesmo texto.
  • A janela de contexto de 1.000.000 de tokens comporta menos texto em média.
  • Um max_tokens antes suficiente pode agora truncar respostas.
  • O custo por requisição equivalente pode aumentar.

Use o endpoint de contagem de tokens antes de enviar prompts grandes:

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)
Enter fullscreen mode Exit fullscreen mode

A Anthropic documenta o recurso na página de contagem de tokens.

Erros, limites de taxa e custo

Semântica HTTP padrão se aplica:

Código Significado Ação recomendada
400 Requisição malformada Verifique thinking, amostragem e prefill
401 Chave inválida ou ausente Verifique ANTHROPIC_API_KEY
429 Limite de taxa atingido Leia retry-after e tente novamente depois
200 com refusal Recusa de segurança Não envie para retry automático

Sobre custo:

  • Até 31 de agosto de 2026:
    • US$ 2 por milhão de tokens de entrada
    • US$ 10 por milhão de tokens de saída
  • Depois disso:
    • US$ 3 por milhão de tokens de entrada
    • US$ 15 por milhão de tokens de saída

A taxa por token passa a corresponder ao Sonnet 4.6, mas o novo tokenizador pode gerar mais tokens para texto equivalente. Modele custos com contagem de tokens, não por estimativa manual.

Para aprofundar, veja a 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 chamadas do Sonnet 5 no Apidog

Depois do primeiro curl, salve suas requisições em um ambiente reproduzível. No Apidog, você pode manter headers, variáveis, coleções e testes no mesmo fluxo.

1. Crie a requisição

No Apidog:

  1. Crie uma nova requisição HTTP.
  2. Defina o método como POST.
  3. Use a URL: 
https://api.anthropic.com/v1/messages
Enter fullscreen mode Exit fullscreen mode

Adicione os headers:

anthropic-version: 2023-06-01
content-type: application/json
x-api-key: {{ANTHROPIC_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

Use um corpo JSON inicial:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Write a haiku about API testing."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

2. Armazene a chave como variável de ambiente

Crie um ambiente, por exemplo:

Produção Anthropic
Enter fullscreen mode Exit fullscreen mode

Adicione a variável:

ANTHROPIC_API_KEY=sk-ant-...
Enter fullscreen mode Exit fullscreen mode

Depois referencie no header:

x-api-key: {{ANTHROPIC_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

Assim, a chave fica fora do corpo da requisição e pode ser trocada por ambiente.

3. Salve chamadas em uma coleção

Crie uma coleção para Sonnet 5 com, por exemplo:

  • chamada simples de Messages
  • chamada com thinking desativado
  • chamada com streaming
  • chamada de contagem de tokens
  • chamada com ferramentas, se sua aplicação usar tool calling

Isso evita copiar comandos curl manualmente entre membros da equipe.

4. Adicione testes automatizados

Adicione asserções para detectar regressões rapidamente:

  • status HTTP é 200
  • model é claude-sonnet-5
  • stop_reason existe
  • stop_reason não é max_tokens
  • usage.output_tokens é maior que 0

Essas verificações ajudam a detectar truncamento causado por max_tokens, especialmente após a mudança do tokenizador e o pensamento adaptativo ativado por padrão.

5. Simule o endpoint

Use mock no Apidog para retornar respostas compatíveis com o formato Messages. Isso permite testar:

  • parser da resposta
  • tratamento de stop_reason
  • UI do frontend
  • camada de integração
  • fluxos de erro

Sem gastar tokens reais durante desenvolvimento.

Se você está saindo do Postman, veja o guia sobre testes de API sem Postman em 2026. Se prefere terminal, o guia completo da CLI do Apidog mostra como executar testes salvos em pipelines.

Perguntas frequentes

Qual é o ID do modelo Claude Sonnet 5?

Use:

claude-sonnet-5
Enter fullscreen mode Exit fullscreen mode

É a string exata, sem sufixo de data. Use no campo model da requisição Messages.

Para uma visão geral do modelo, leia o que é o Claude Sonnet 5.

Por que minha saída está sendo cortada com max_tokens?

Porque o pensamento adaptativo está ativado por padrão e seus tokens contam dentro de max_tokens. Além disso, o novo tokenizador gera cerca de 30% mais tokens para o mesmo texto.

Opções:

  • aumentar max_tokens
  • usar streaming
  • desativar pensamento com thinking: {"type": "disabled"}

Preciso mudar meu código ao migrar do Sonnet 4.6?

Sim, revise três pontos:

  1. Remova temperature, top_p e top_k não padrão.
  2. Remova thinking: {type: "enabled", budget_tokens: N}.
  3. Remova pré-preenchimento de mensagens do assistente.

Streaming e formatos de resposta permanecem iguais. Se você também usa Opus, veja o guia da API Opus 4.8.

Uma recusa é um erro?

Não. Uma recusa retorna HTTP 200 com:

{
  "stop_reason": "refusal"
}
Enter fullscreen mode Exit fullscreen mode

Trate como resposta normal com motivo de parada diferente de end_turn. Não envie para retry automático.

Quanto custa a API do Sonnet 5?

A precificação introdutória até 31 de agosto de 2026 é:

  • US$ 2 por milhão de tokens de entrada
  • US$ 10 por milhão de tokens de saída

Depois disso:

  • US$ 3 por milhão de tokens de entrada
  • US$ 15 por milhão de tokens de saída

Como o novo tokenizador pode gerar mais tokens para texto equivalente, use contagem de tokens para estimar custo real.

Top comments (0)