Como usar a API do Claude Sonnet 5.5

TL;DR

Claude Sonnet 5.5 é um modelo rápido para fluxos de trabalho bem delimitados de codificação, documentos e uso de ferramentas. A Anthropic relata mais de 30% de saída mais rápida do que o Sonnet 5 nas mesmas taxas padrão de tokens. Comece com uma chave CometAPI, o ID do modelo claude-sonnet-5-5 e uma pequena solicitação Messages ou Chat Completions. Agentes existentes devem retestar raciocínio, escolha de ferramentas e replay de histórico antes da implantação.

Key Takeaways

• Use Claude Sonnet 5.5 e combine o formato da solicitação com o seu endpoint.
• Comece com uma única solicitação curta antes de adicionar imagens, ferramentas ou contexto longo.
• Use Messages para controles específicos do Claude; use Chat Completions para um aplicativo que já utiliza o SDK da OpenAI.
• Revise mudanças de raciocínio e seleção de ferramentas antes de migrar loops de agentes existentes.
• Compare qualidade de tarefas aceitas, latência, uso de tokens e acertos de cache antes de aumentar o tráfego.

What Is Claude Sonnet 5.5?

A Claude Sonnet 5.5 API é a interface programática para o modelo Sonnet 5.5 da Anthropic. Ela é projetada para tarefas como desenvolvimento de software, análise de repositórios, automação de suporte ao cliente, processamento de documentos, compreensão de imagens, agentes que usam ferramentas e fluxos de trabalho profissionais estruturados.

A Anthropic posiciona o Sonnet 5.5 como um complemento mais rápido e de menor custo ao Opus 5.5, o segundo modelo da família Claude 5.5, otimizado para codificação bem delimitada, correção de bugs, criação de documentos e slides, e tarefas profissionais do dia a dia. Desenvolvedores podem acessar a Claude Sonnet 5.5 API no CometAPI usando claude-sonnet-5-5.

A Anthropic confirma janela de contexto de 1M tokens e limite de saída síncrona de 128K. A saída em lote pode atingir 300K tokens apenas por meio de Message Batches com o cabeçalho beta output-300k-2026-03-24. O suporte a recursos de Gateway deve ser verificado separadamente do suporte em nível de modelo.

How Does Claude Sonnet 5.5 Perform on Official Benchmarks?

A comparação compacta abaixo ajuda a identificar cargas de trabalho para avaliar antes de adotar a API. Resultados de benchmark não substituem testar seus próprios prompts e loops de ferramentas.

Os resultados de benchmark e notas de avaliação da Anthropic fornecem a base para esta comparação. O resultado do Terminal-Bench do Opus 5.5 usa esforço Xhigh; o FrontierCode relata resultados separados de Max e Xhigh para o Sonnet 5.5; o OSWorld é uma avaliação parcial. GDPval-AA e AA-Briefcase foram executados pela Artificial Analysis em um deployment pré-lançamento na Claude Platform com um bug de saída estruturada que provavelmente subestimou a pontuação do Sonnet 5.5; a Anthropic diz que o bug já foi corrigido. Esses resultados devem orientar testes de cargas de trabalho em vez de garantir resultados de produção. Humanity’s Last Exam usa ferramentas; Chartography não. As novas linhas usam as pontuações publicadas pela Anthropic. A imagem original abaixo é mantida; a tabela expandida inclui três avaliações adicionais.

Comparação oficial de benchmarks do Claude Sonnet 5.5

What Changed in Claude Sonnet 5.5 API From Sonnet 5?

As mudanças de migração para raciocínio, escolha de ferramentas e replay de histórico afetam loops de agentes existentes. A tabela resume essas mudanças operacionais; não é um inventário completo de recursos.

Breaking Changes to Check

Verifique todas as cinco mudanças disruptivas: substitua o raciocínio disabled por between_tools; remova forced tool choice; preserve blocos de raciocínio compatíveis e histórico de conversa inalterado; migre computer_20251124 para computer_toolset_20260801 na Claude API e Google Cloud; e substitua pareamentos de advisor não suportados. A Amazon Bedrock ainda aceita computer_20251124. Advisors não suportados incluem Opus 4.8, 4.7, 4.6, Sonnet 5, Sonnet 4.6 e Haiku 5.5. Opus 5.5 é um substituto suportado. Leia blocos de resposta por tipo. Verifique compatibilidade da plataforma e do gateway antes da implantação. Guia oficial de migração.

Additional Capabilities and Workflow Changes

Use o guia de recursos oficial para revisar atualizações de progresso, esforço por mensagem e controles no meio da conversa. Confirme suporte de gateway antes de habilitar recursos beta.

What Do You Need Before Using the Claude Sonnet 5.5 API?

• Uma conta CometAPI, chave de API, acesso ao modelo e saldo de faturamento disponível.
• Um terminal com cURL; Python e pip ou Node.js e npm para exemplos de SDK.
• Um endpoint selecionado: /v1/messages ou /v1/chat/completions.
• COMETAPI_KEY armazenada no ambiente do servidor, além de acesso de rede a https://api.cometapi.com.
• Um prompt de teste curto e uma verificação clara de saída utilizável, status de conclusão e uso de tokens.

How Do You Access Claude Sonnet 5.5 API Through CometAPI?

Escolha a Messages API quando o próprio comportamento do Claude importar. Escolha a API compatível com OpenAI quando seu aplicativo já alternar entre Claude, GPT, Gemini, DeepSeek ou outros modelos por meio da mesma camada de abstração.

Step 1: Store the API Key

Crie uma chave no console de chaves da CometAPI, depois defina-a em seu ambiente de execução.

Defina a chave CometAPI em um shell POSIX

export COMETAPI_KEY="YOUR_COMETAPI_KEY"

Defina a chave CometAPI no PowerShell

$env:COMETAPI_KEY="YOUR_COMETAPI_KEY"

Step 2: Make the First Messages Request

Envie a primeira solicitação Messages compatível com a Anthropic

curl https://api.cometapi.com/v1/messages \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 2048,
    "messages": [{"role": "user", "content": "Explain exponential backoff in three bullet points."}]
  }'

Inspecione os content blocks, stop_reason e usage antes de adicionar mais controles. A sintaxe cURL acima usa um shell POSIX.

Step 3: Use the Anthropic Python SDK

Instale o SDK Python da Anthropic

pip install anthropic

Leia blocos de texto e usage com o SDK da Anthropic

import os
import anthropic

anthropic_client = anthropic.Anthropic(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com",
)

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Review this migration plan and list the three biggest risks."}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)
print("Completion:", response.stop_reason)
print("Usage:", response.usage)

Step 4: Use the OpenAI Python SDK

Instale o SDK Python da OpenAI

pip install openai

Chame o Sonnet 5.5 via Chat Completions compatível com OpenAI

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
        {
            "role": "system",
            "content": "You are a concise software engineering assistant."
        },
        {
            "role": "user",
            "content": "Review this function and identify the highest-risk bug."
        }
    ],
)

print(response.choices[0].message.content)

Essa abordagem é útil quando um aplicativo já usa a interface do SDK da OpenAI. Uma integração básica de texto pode exigir apenas uma nova base URL, chave de API e ID de modelo, mas migrações de produção ainda devem verificar parâmetros suportados, formatos de resposta, chamadas de ferramenta, eventos de streaming, timeouts e contabilização de tokens.

Step 5: Use JavaScript in Node.js

Instale o SDK Node.js da OpenAI

npm install openai

Chame o Sonnet 5.5 a partir de um módulo ES no Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.COMETAPI_KEY,
  baseURL: "https://api.cometapi.com/v1",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5-5",
  messages: [
    {
      role: "user",
      content: "Create a TypeScript function that validates an email address.",
    },
  ],
});

console.log(response.choices[0].message.content);

Para aplicações backend em Node.js, mantenha COMETAPI_KEY no ambiente do servidor em vez de enviá-la para um cliente de navegador.

Claude Sonnet 5.5 Thinking and Effort Levels

A API tem esforço padrão alto; aplicativos do Claude e Claude Code usam médio. Selecione esforço considerando qualidade de tarefas aceitas, latência e custo de tokens. A tabela abaixo é um ponto de partida editorial, não uma classificação oficial de cargas de trabalho.

Evite atribuir automaticamente o nível de esforço mais alto a toda solicitação. Cargas de trabalho de agentes podem ficar materialmente mais caras quando raciocínio adicional também cria mais chamadas de ferramentas e saídas mais longas. Selecione a configuração com avaliação em nível de tarefa. Use raciocínio adaptativo para Xhigh e Max, depois compare qualidade de tarefas aceitas e custo total com níveis mais baixos. Orientação oficial de esforço.

Configure Effort Through Messages

Este exemplo usa o cliente Anthropic inicializado acima. Teste os mesmos controles na sua rota CometAPI antes da implantação.

Configurar raciocínio adaptativo e esforço alto

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=8192,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "Audit this service migration plan."}],
)

Turn Off Up-Front Thinking

Use thinking={"type": "between_tools"} em esforço low, medium ou high. Use raciocínio adaptativo para xhigh ou max. between_tools não aceita campos display ou budget_tokens e não permite alterar esforço no meio da conversa.

Preserve Thinking in Tool Loops

Retorne blocos de conteúdo originais do assistente antes de anexar resultados de ferramentas. O raciocínio preservado depende do modelo, do prefixo da conversa e da conta produtora. Binding de prefixo é aplicado por padrão na Claude API, Amazon Bedrock e Google Cloud para contas criadas em ou após 31 de agosto de 2026, 00:00 UTC. Não presuma que todo gateway exponha os mesmos controles de binding.

How to Stream Claude Sonnet 5.5 Responses

Stream Long Responses

Streaming é útil para interfaces de chat, assistentes de codificação e respostas longas porque os usuários podem ver a saída antes de a geração terminar.

Transmitir texto via Chat Completions compatível com OpenAI

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
)

stream = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
        {
            "role": "user",
            "content": "Explain how a retrieval-augmented generation pipeline works."
        }
    ],
    stream=True,
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Streaming normalmente não reduz o número total de tokens gerados. Seu principal benefício é a latência percebida. Aplicações também devem lidar explicitamente com streams interrompidos, saídas parciais, novas tentativas de rede e cancelamento.

Use Tools With Automatic Selection

Use tool_choice={"type": "auto"}. Valide cada nome e argumento de ferramenta, aplique autorização e timeouts, retorne resultados estruturados e limite iterações. Execução obrigatória de ferramentas pertence à orquestração do aplicativo.

Defina uma ferramenta de consulta de ticket e solicite seleção automática

tools = [{
    "name": "lookup_ticket",
    "description": "Retrieve a support ticket by ID",
    "input_schema": {
        "type": "object",
        "properties": {"ticket_id": {"type": "string"}},
        "required": ["ticket_id"],
        "additionalProperties": False,
    },
}]

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    tools=tools,
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Look up ticket T-123 and summarize its status."}],
)

Um bloco tool_use solicita uma ação; esta primeira chamada não a executa. Valide a solicitação no seu servidor, execute a operação, anexe o conteúdo do assistente inalterado e envie um tool_result correspondente. O esquema neste exemplo ainda requer validação da aplicação; suporte rígido a ferramentas deve ser verificado na rota selecionada.

Use Prompt Caching for Repeated Context

Prompt caching é útil quando solicitações contêm repetidamente o mesmo grande prefixo, como políticas de sistema, esquemas de ferramentas, mapas de repositório, documentação de produto, instruções reutilizáveis ou manuais de referência.

Sonnet 5.5 requer um prefixo de prompt cacheável de pelo menos 512 tokens. Prefixos mais curtos são processados sem cache, mesmo com cache_control. Verifique cache_creation_input_tokens e cache_read_input_tokens; ambos zero significa que nenhum cache foi usado. Confirme suporte na sua rota de gateway. Referência de prompt caching.

Organize contexto estável antes do conteúdo dinâmico da solicitação

Stable system instructions
Stable tools
Stable repository or knowledge context
---------------- cache boundary ----------------
Current user request
Current retrieved context

A taxa atual de leitura de cache da CometAPI é $0.16 por milhão de tokens, comparada a $1.60 para entrada nova. Escritas de cache são cobradas separadamente. Verifique acertos de cache em metadados de uso antes de estimar economias.

Cache é especialmente útil para agentes de codificação e assistentes corporativos que reutilizam grandes prefixos de contexto em múltiplos turnos. A economia ainda depende de acertos reais de cache; reescrever frequentemente o prefixo estável pode remover a maior parte do benefício esperado.

Send Images Using the Selected Endpoint Schema

Sonnet 5.5 aceita entrada de texto e imagem. O JSON abaixo é um payload compatível com Chat Completions da OpenAI; substitua a URL de imagem de exemplo por uma imagem publicamente acessível que você controle. Messages usa um esquema diferente para blocos de imagem.

Enviar uma imagem em um payload de Chat Completions

{
  "model": "claude-sonnet-5-5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Find the three most important UI problems in this screenshot."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/interface.png"
          }
        }
      ]
    }
  ]
}

A forma exata da solicitação multimodal pode diferir entre a interface nativa do Claude e a compatível com OpenAI, então use o esquema do endpoint que você realmente implantar em vez de presumir que os dois formatos são intercambiáveis.

Handle Safeguards and Retained Data

Registre recusas e comportamento de fallback como estados explícitos da aplicação. A Anthropic descreve salvaguardas e disponibilidade de zero-data-retention para seu serviço. Verifique separadamente os arranjos de retenção e roteamento aplicáveis do seu gateway antes de enviar material de produção.

Claude Sonnet 5.5 vs Sonnet 5 vs Opus 5.5

Os rótulos qualitativos abaixo são orientações editoriais de roteamento com base no escopo da tarefa, não notas oficiais de desempenho. Valide esses papéis em cargas de trabalho representativas. Arquitetura detalhada não é inferida de pontuações de benchmark.

Encaminhe tarefas difíceis para um modelo de escalonamento

Routine task
    ↓
Claude Sonnet 5.5
    ↓
Confidence / validation failure?
    ├── No → Return result
    └── Yes → Escalate difficult case
                 ↓
              Opus-class model

Esse padrão de roteamento pode reduzir custos enquanto preserva acesso a um nível de raciocínio mais forte para casos difíceis.

Claude Sonnet 5.5 Pricing Through CometAPI

Verificado em 10 de outubro de 2026: entrada/saída da CometAPI permanecem $1.60/$8 por milhão de tokens, 20% abaixo dos $2/$10 da Anthropic. Leitura/gravação de cache da CometAPI permanecem $0.16/$2; leitura/gravação de cache atuais da Anthropic são $0.10/$2.50 para gravação de cinco minutos. A página de lançamento ainda mostra leituras de cache de $0.20; esta revisão usa a referência de cache atual. Preços de gateway podem mudar independentemente.

A diferença entre preço por token e custo por tarefa importa para aplicações de agente. Um agente de codificação pode gerar menos tokens mas ainda realizar várias rodadas de chamadas de ferramentas, leituras de cache, inspeção de código, novas tentativas e validação. O custo por tarefa concluída com sucesso é, portanto, geralmente mais informativo do que apenas o preço de tokens de entrada.

Estime cobranças de tokens de entrada nova e de saída

Input:
100,000 / 1,000,000 × $1.60 = $0.16

Output:
5,000 / 1,000,000 × $8.00 = $0.04

Estimated model-token cost:
$0.20

Cobranças de ferramentas, operações de cache, etapas repetidas de agente ou outros recursos faturáveis podem alterar o custo final.

Taxas rechecadas em 10 de outubro de 2026 contra a página atual do modelo da CometAPI. Preços de entrada/saída nova permanecem inalterados, então o exemplo calculado continua $0.16 + $0.04 = $0.20 para 100,000 tokens de entrada nova e 5,000 tokens de saída. Exclui gravações de cache, leituras de cache, taxas de ferramentas e novas tentativas. Recheque faturamento específico da rota antes de orçar.

Control Cost per Accepted Task

Há várias maneiras práticas de reduzir gastos sem trocar de modelo imediatamente. Primeiro, defina claramente critérios de conclusão:

Defina um formato focado de aceitação de resposta

Return only:
1. the root cause;
2. the affected file;
3. the smallest safe fix;
4. one regression test.

Segundo, aparar contexto recuperado antes de enviá-lo. Uma janela de contexto de 1M tokens é um limite de capacidade, não uma meta. Terceiro, reutilize contexto estável por meio de prompt caching. Quarto, selecione o esforço por carga de trabalho em vez de definir Alto para toda solicitação. Quinto, meça custo por tarefa aceita:

Calcular custo por tarefa aceita

Total API cost
÷
Number of outputs accepted without rework

Uma solicitação mais barata não é necessariamente um fluxo de trabalho mais barato se causar tentativas extras, correções ou chamadas de ferramentas.

How Do You Migrate From Sonnet 5 to Claude Sonnet 5.5 API?

1. Mantenha a configuração de produção anterior disponível para rollback.
2. Altere o ID do modelo de claude-sonnet-5 para claude-sonnet-5-5.
3. Aplique as mudanças de raciocínio, seleção automática de ferramentas e histórico descritas acima.
4. Reproduza solicitações representativas, incluindo ferramentas, imagens e streaming.
5. Compare saídas aceitas, taxa de correção humana, latência p50/p95 e custo total da tarefa.
6. Teste novas tentativas, recusas, cancelamentos e streams interrompidos.
7. Verifique acertos de cache e comportamento do orçamento de saída a partir dos metadados de uso.
8. Libere um canário de tráfego pequeno e expanda apenas após atingir os limites de aceitação.

Troubleshooting Claude Sonnet 5.5 API Errors

Não repita solicitações malformadas ou falhas de autenticação sem alterações. Evite ações duplicadas de ferramentas ao reproduzir execuções de agentes interrompidas.

Claude Sonnet 5.5 Production Best Practices

Escolha uma carga de trabalho, defina um gate de aceitação e avalie a aplicação completa. Registre ID do modelo, endpoint, esforço, latência, uso de tokens e cache, falhas de ferramentas, status de conclusão e resultado de tarefa aceita. Mantenha chaves no lado do servidor e configure timeouts, novas tentativas limitadas e limites de iteração de agentes.

Measure Workflow Quality and Reliability

Para agentes de codificação, também acompanhe testes aprovados, arquivos modificados sem necessidade, patches revertidos e conclusão bem-sucedida sem intervenção humana.

Example: Fix a Well-Scoped Repository Bug

Forneça o teste falho, arquivos fonte relevantes e o comportamento esperado. Solicite um patch focado com uma verificação de regressão. O gate de aceitação é uma correção reproduzível, passando testes relevantes, sem edições não relacionadas. Compare custo total de API e ferramentas com patches aceitos.

Example: Triage a Support Ticket

Recupere o problema do cliente e trechos aprovados da base de conhecimento. Peça ao modelo para classificar o problema, redigir uma resposta embasada em evidências e sinalizar casos que exigem escalonamento. Aceite um resultado apenas quando suas afirmações corresponderem ao material recuperado e a decisão de roteamento seguir a política de suporte.

Example: Review a Document and Screenshot

Forneça um procedimento aprovado e uma captura de tela da interface correspondente. Peça discrepâncias com referências ao trecho relevante e ao elemento de UI visível. Exija que um revisor confirme as descobertas antes de alterar o procedimento.

Conclusion

Claude Sonnet 5.5 oferece às equipes um candidato prático para fluxos de trabalho rápidos de codificação, suporte, documentos e uso de ferramentas. Comece com uma solicitação funcional ao CometAPI e, em seguida, adicione os controles de que seu aplicativo precisa.

Migração requer mais do que substituir o ID do modelo: verifique configurações de raciocínio, seleção automática de ferramentas, parsing de respostas e replay de histórico. Promova o modelo quando suas avaliações de carga de trabalho mostrarem um equilíbrio aceitável de qualidade, latência e custo; reserve um nível mais forte para tarefas que falhem no seu gate de aceitação.

FAQ

How Should Teams Rotate a Claude Sonnet 5.5 API Key Without Downtime?

Armazene chaves em um gerenciador de segredos no servidor e permita que workers recarreguem credenciais sem incorporá-las no código da aplicação. Se o provedor suportar chaves ativas sobrepostas, introduza a substituta primeiro, valide uma pequena solicitação, mude workers gradualmente e então revogue a chave anterior. Monitore erros de autenticação durante a troca e evite registrar qualquer uma das chaves.

How Can a Claude Sonnet 5.5 Job Resume After a Worker Restart?

Persista um identificador de job, a última etapa concluída, a configuração da solicitação e registros de execução de ferramentas. Retome a partir de um checkpoint verificado. Antes de reproduzir uma ação de ferramenta, verifique se ela já foi concluída e se é seguro repetir. Uma transcrição salva por si só não impede tickets, mensagens ou gravações em banco de dados duplicados.

How Should Teams Detect Claude Sonnet 5.5 Behavior Changes Over Time?

Mantenha um conjunto de avaliação datado com respostas aceitas ou verificações de aceitação, juntamente com versões de SDK e configurações de solicitação. Reexecute-o periodicamente e após mudanças de provedor, SDK, prompt ou roteamento. Compare sucesso de tarefas, taxa de correção, latência e custo total. Se uma conta oferecer pinagem de versão, confirme suas garantias antes de depender disso; mantenha uma rota de rollback para fluxos de trabalho críticos.