Como Usar a API Claude Sonnet 5.5: Primeira Chamada, Desafios, Estratégias, Ferramentas e Streaming

Para usar a API Claude Sonnet 5.5, envie uma requisição POST para https://api.anthropic.com/v1/messages com "model": "claude-sonnet-5-5", sua chave no cabeçalho x-api-key e anthropic-version: 2023-06-01. Custa US$2 por milhão de tokens de entrada e US$10 por milhão de tokens de saída, lê até 1M de tokens de contexto, escreve até 128K, executa pensamento adaptativo por padrão e tem high (alto) como esforço padrão.

A Anthropic lançou o Sonnet 5.5 em 28 de setembro de 2026 (o que é Claude Sonnet 5.5 aborda especificações e benchmarks). Este guia mostra uma primeira chamada em curl, Python e TypeScript, depois esforço, pensamento, ferramentas, streaming, recusas e limites de taxa. Está movendo código do Sonnet 5? O guia Sonnet 5.5 vs Sonnet 5 contém todas as mudanças drásticas com JSON de antes/depois. Você pode enviar cada requisição abaixo do Apidog e mantê-la como um teste salvo com asserções.

API Claude Sonnet 5.5 em resumo

Fontes: a página do modelo Sonnet 5.5 e o guia de migração.

Exemplo de API Claude Sonnet 5.5: sua primeira chamada

Crie uma chave (o guia de chave de API da Anthropic explica como fazer) e exporte-a como ANTHROPIC_API_KEY em vez de codificá-la diretamente. Em seguida, envie isto:

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-5",
    "max_tokens": 4096,
    "output_config": {"effort": "medium"},
    "messages": [{"role": "user", "content": "Explain idempotency keys in two sentences."}]
  }'

O SDK Python lê ANTHROPIC_API_KEY do ambiente:

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Explain idempotency keys in two sentences."}],
)
print(response.stop_reason)
for block in response.content:
    if block.type == "text":
        print(block.text)

O TypeScript funciona da mesma forma:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 4096,
  output_config: { effort: "medium" },
  messages: [{ role: "user", content: "Explain idempotency keys in two sentences." }],
});
for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}

Leia os blocos de conteúdo por type. O pensamento adaptativo está ativado por padrão, então uma resposta pode começar com um bloco thinking, e o código que lê content[0].text pode quebrar. Tokens de pensamento são faturados como saída e contam para max_tokens mesmo quando seu texto está oculto, então deixe margem acima da resposta que você espera.

Escolha um nível de esforço

O esforço, definido em output_config.effort, é seu principal seletor de custo e qualidade. A Anthropic recalibrou os níveis para o Sonnet 5.5, então uma configuração do Sonnet 5 não se transfere; faça uma nova varredura em suas próprias avaliações. O guia de prompt sugere estes pontos de partida:

A diferença é grande. Em execuções próprias do Terminal-Bench 4.0 da Anthropic, o Sonnet 5.5 obteve 43,0% em high por US$1,94 por tentativa e 70,6% em max por US$12,54. A análise de preços do Sonnet 5.5 detalha o custo por requisição.

Planeje para três comportamentos. De medium para cima, o modelo pensa antes de quase toda resposta, mesmo um cumprimento, e solicitar que ele pense menos não é confiável: diminua o esforço em vez disso. Em low e medium, ele tende a verificar no início de tarefas agênticas longas. E mudar o esforço de nível superior entre requisições invalida o cache de prompts. Para mudar de nível no meio da conversa e manter o cache, use o esforço por mensagem (beta, cabeçalho anthropic-beta: mid-conversation-output-config-2026-07-01): adicione uma mensagem role: "system" com content vazio e o novo output_config.effort.

Controle o pensamento: adaptativo ou between_tools

Omita o campo thinking e o Sonnet 5.5 executará pensamento adaptativo. Ele rejeita {"type": "disabled"} com um erro 400. Para desativar o pensamento inicial, envie between_tools, a configuração mais baixa:

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 16000,
  "thinking": {"type": "between_tools"},
  "output_config": {"effort": "high"},
  "messages": [{"role": "user", "content": "..."}]
}

Regras para between_tools do Sonnet 5.5:

• Funciona apenas em low, medium ou high. Em xhigh ou max, retorna 400.
• Não aceita outro campo. Adicionar display, budget_tokens ou block_binding retorna 400.
• Não precisa de cabeçalho beta e funciona em todas as plataformas.
• O esforço não pode mudar no meio da conversa enquanto estiver definido.
• Versões do SDK que não o definem falham na verificação de tipo, então atualize seu SDK.

Sob o pensamento adaptativo, display decide o que os blocos de pensamento contêm. O padrão, omitted, retorna cada bloco thinking com um campo thinking vazio mais uma signature. summarized retorna resumos legíveis. updates (beta, cabeçalho thinking-display-updates-2026-08-18) retorna apenas atualizações de progresso como texto.

As atualizações de progresso são a mudança mais provável de confundir uma UI. O Sonnet 5.5 coloca notas com mais de uma ou duas frases, escritas entre chamadas de ferramentas, em seus próprios blocos thinking em vez de text. Sob o padrão omitted, esses blocos são vazios, então uma interface de agente que costumava narrar seus passos fica silenciosa. Defina display: "updates" ou "summarized", ou execute between_tools, que retorna as notas com texto. Renderize cada bloco thinking não vazio antes do bloco tool_use que o segue. Pedir por raciocínio no texto da resposta convida a uma recusa de reasoning_extraction, então leia esses blocos em vez disso.

Use ferramentas sem tool_choice forçada

O uso forçado de ferramentas foi removido. Um tool_choice de {"type": "any"} ou {"type": "tool", ...} retorna um erro 400 com esta mensagem, inclusive no endpoint de contagem de tokens:

tool_choice: tipo "tool" e "any" não são suportados para este modelo.

Envie auto, marque a ferramenta strict: true para que sua entrada corresponda ao esquema, e diga ao modelo no prompt quando chamá-la:

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "input_schema": {
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"],
      "additionalProperties": false
    },
    "strict": true
  }],
  "tool_choice": {"type": "auto"},
  "messages": [{"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}]
}

Uma requisição pode carregar no máximo 20 ferramentas estritas, e esquemas estritos precisam de additionalProperties: false em cada objeto. No Amazon Bedrock, ferramentas estritas não estão disponíveis para Sonnet 5.5: envie auto sem strict e valide a entrada em seu código.

Dois detalhes do loop importam. Passe cada bloco thinking de volta inalterado com seu bloco tool_use, incluindo os vazios. E espere a ocasional variação de caixa, como bash para uma ferramenta declarada como Bash. O guia de prompt sugere aceitar correspondências inequívocas, ou retornar um tool_result com is_error: true que indica o nome exato.

Transmita respostas

Adicione "stream": true ao corpo, ou use o auxiliar de stream do SDK. Para codificação agêntica, o guia de prompt recomenda max_tokens de 128.000 com streaming:

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=128000,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Review this diff for bugs: ..."}],
) as stream:
    for event in stream:
        if event.type == "content_block_delta" and event.delta.type == "text_delta":
            print(event.delta.text, end="", flush=True)
    final = stream.get_final_message()

Eventos enviados pelo servidor chegam como message_start, depois content_block_start, content_block_delta e content_block_stop para cada bloco, depois message_delta (transportando stop_reason) e message_stop. Sob omitted, um bloco de pensamento transmite um thinking_delta vazio e um signature_delta, então o texto começa. Espere uma pausa de vários segundos antes que um bloco de atualização de progresso seja aberto.

stream.get_final_message() (TypeScript: stream.finalMessage()) reconstrói blocos completos com suas assinaturas. Anexe esse conteúdo ao histórico como a vez do assistente, inalterado, e mantenha o histórico apenas para anexar. O Sonnet 5.5 assina cada bloco de pensamento sobre a conversa anterior a ele, então em contas criadas em ou após 31 de agosto de 2026 (00:00 UTC), reproduzir um bloco após editar o histórico anterior retorna 400. Os blocos também estão vinculados à conta que os produziu.

Lide com recusas e fallback

Uma recusa não é um erro. Você recebe HTTP 200 com stop_reason: "refusal" e um objeto stop_details cuja categoria é cyber, bio, frontier_llm, reasoning_extraction ou general_harms, além de uma explanation. Exiba a explicação em vez de analisá-la; sua formulação não é estável. Crie uma ramificação em stop_reason antes de ler content.

O fallback do lado do servidor é opcional. Adicione "fallbacks": "default" e o cabeçalho anthropic-beta: server-side-fallback-2026-07-01 (beta, apenas API Claude), e a API tenta novamente recusas de cyber e frontier_llm no Sonnet 5. As outras três categorias não são tentadas novamente. O campo model da resposta nomeia o modelo que a serviu, e um bloco de conteúdo fallback marca a transição.

Limites de taxa

O Sonnet 5.5 tem seu próprio limite de taxa, separado do do Sonnet 5. A página de limites de taxa lista quatro níveis:

Para tratamento de 429 e `backoff`, consulte o guia de limite de taxa excedido.

Teste a API Claude Sonnet 5.5 no Apidog

Requisições salvas tornam as comparações de esforço e a depuração de stream repetíveis. Veja a configuração no Apidog:

1. Crie um ambiente e adicione ANTHROPIC_API_KEY como uma variável. Referencie-o como {{ANTHROPIC_API_KEY}} no cabeçalho x-api-key, ao lado de anthropic-version e content-type.
2. Crie uma requisição POST para https://api.anthropic.com/v1/messages, cole o corpo da primeira chamada e salve-a.
3. Adicione asserções: status é 200, $.stop_reason é igual a end_turn, $.usage.output_tokens é maior que 0, e $.content[*].type contém text. Uma recusa agora falha no teste em vez de passar silenciosamente.
4. Duplique a requisição com "stream": true. O Apidog mostra a resposta text/event-stream evento por evento, para que você possa ver o thinking_delta vazio, o signature_delta e o texto chegarem em ordem.
5. Clone-o novamente com "model": "claude-sonnet-5" e mantenha o par em uma pasta: o mesmo prompt, dois modelos, usage lado a lado.

Para padrões mais amplos, veja teste de aplicações LLM e teste de APIs de agentes de IA.

Perguntas Frequentes

Qual é o ID do modelo Claude Sonnet 5.5? claude-sonnet-5-5, sem sufixo de data, na API Claude, Google Cloud, Microsoft Foundry e Plataforma Claude na AWS. No Amazon Bedrock, é anthropic.claude-sonnet-5-5.

Posso desativar o pensamento completamente? Não. disabled retorna 400. between_tools é a configuração mais baixa: sem pensamento inicial, com esforço low, medium ou high.

Por que minha requisição Sonnet 5 retorna 400 no Sonnet 5.5? Verifique primeiro por thinking.type: "disabled" e um tool_choice forçado. O guia Sonnet 5.5 vs Sonnet 5 aborda todas as cinco mudanças drásticas e suas correções.

Existe uma API Claude Sonnet 5.5 gratuita? A API da Anthropic é pré-paga, e nenhuma página oficial lista um crédito de inscrição gratuito. Um plano de chat Claude também não inclui acesso à API. O guia de API gratuita cobre programas de crédito e o caminho pago mais barato.

Próximo passo

Envie a requisição da primeira chamada em medium, depois execute-a novamente em high e compare usage.output_tokens e a qualidade da resposta em um prompt de sua própria carga de trabalho. Baixe o Apidog para salvar ambas as execuções com asserções. Se você preferir trabalhar no terminal, veja Claude Sonnet 5.5 no Código Claude.