Claude Platform Docs
Modelos e preçosClaude Sonnet 5

Migrando para o Claude Sonnet 5

Migre para o Claude Sonnet 5 a partir de modelos Claude anteriores: IDs de modelo, mudanças incompatíveis e checklists de migração.

O Claude Sonnet 5 oferece a melhor combinação de velocidade e inteligência na família de modelos Claude. Ele se baseia no Claude Sonnet 4.6.

O Claude Sonnet 5 é uma atualização direta (drop-in) para o Claude Sonnet 4.6, com preço de $2/$10 USD por milhão de tokens de entrada/saída; consulte Preços para detalhes. Há duas mudanças incompatíveis na API para código que já roda no Claude Sonnet 4.6. Primeiro, o adaptive thinking (pensamento adaptativo) está ativado por padrão e o "extended thinking" (pensamento estendido) manual (thinking: {type: "enabled", budget_tokens: N}) retorna um erro 400, portanto requisições que rodavam sem pensamento agora podem retornar blocos thinking antes do primeiro bloco text, e código que lê o conteúdo por posição deve selecionar blocos de conteúdo por type. Segundo, parâmetros de amostragem (temperature, top_p, top_k) definidos com valores diferentes do padrão retornam um erro 400. Use o pensamento adaptativo com o parâmetro effort para controlar a profundidade do pensamento. O Claude Sonnet 5 suporta o mesmo conjunto de recursos do Claude Sonnet 4.6, incluindo a "context window" (janela de contexto) de 1M de tokens, pensamento adaptativo, "prompt caching" (cache de prompt), processamento em lote, a Files API, suporte a PDF, visão e o conjunto completo de ferramentas do lado do servidor e do lado do cliente. Na Claude API e no Google Cloud, o Claude Sonnet 5 também suporta computer use (uso de computador) como o toolset estável computer_toolset_20260801 e a ferramenta de uso de navegador para tarefas dentro de páginas web, nenhum dos quais o Claude Sonnet 4.6 suporta; integrações existentes na versão anterior computer_20251124 continuam funcionando sem alterações em ambos os modelos. Para atualizar uma integração existente, consulte Migrar de computer_20251124. O Priority Tier não está disponível no Claude Sonnet 5. O Claude Sonnet 5 também usa um novo tokenizador.

Migrando para o Claude Sonnet 5 a partir do Claude Sonnet 4.6

Atualize o nome do seu modelo

# Migração para o Sonnet
model = "claude-sonnet-4-6"  # Before
model = "claude-sonnet-5"  # After

O que mudou

Os itens 4 e 5 na lista a seguir são mudanças incompatíveis. max_tokens continua sendo um limite rígido para a saída total (pensamento mais texto de resposta), portanto revise-o para cargas de trabalho que rodavam sem pensamento no Claude Sonnet 4.6.

  1. Novo tokenizador: O Claude Sonnet 5 usa um novo tokenizador. O mesmo texto de entrada produz aproximadamente 30% mais tokens do que no Claude Sonnet 4.6. O aumento exato depende do conteúdo. Requisições, respostas e eventos de streaming mantêm o mesmo formato, e nenhuma alteração de código é necessária, mas tudo o que você mede ou orça em tokens muda: os campos usage e os resultados de contagem de tokens para o mesmo texto são maiores, a janela de contexto de 1M de tokens comporta menos texto, e um limite max_tokens ajustado para o Claude Sonnet 4.6 pode truncar uma saída equivalente. O preço por token é menor ($2/$10 USD contra $3/$15 USD do Claude Sonnet 4.6 por milhão de tokens de entrada/saída), mas o custo de uma requisição equivalente não cai em proporção direta. Execute novamente a contagem de tokens no Claude Sonnet 5 em vez de reutilizar contagens medidas em modelos anteriores.

  2. 128k tokens máximos de saída (inalterado): O Claude Sonnet 5 suporta até 128k tokens de saída, o mesmo que o Claude Sonnet 4.6. Os valores existentes de max_tokens permanecem válidos. Leve em conta o novo tokenizador ao dimensioná-los.

  3. Preenchimento prévio de mensagem do assistente (inalterado): Preencher previamente a mensagem do assistente retorna um erro 400 no Claude Sonnet 5, o mesmo que no Claude Sonnet 4.6. Se você removeu o preenchimento prévio ao migrar para o Claude Sonnet 4.6, nenhuma alteração adicional é necessária. Use saídas estruturadas, instruções no prompt do sistema ou output_config.format em vez disso.

  4. Pensamento adaptativo ativado por padrão: No Claude Sonnet 4.6, requisições sem um campo thinking rodam sem pensamento; no Claude Sonnet 5, as mesmas requisições rodam com pensamento adaptativo. Para desativar o pensamento, passe thinking: {type: "disabled"}. O pensamento estendido manual (thinking: {type: "enabled", budget_tokens: N}) não é suportado e retorna um erro 400. Use o parâmetro effort (padrão high) para controlar a profundidade do pensamento.

    Com o pensamento ativado, uma resposta pode começar com um ou mais blocos thinking antes do primeiro bloco text, retornados com um campo thinking vazio no padrão display: "omitted". Código que lê a resposta por posição, como content[0].text ou um handler de stream que trata o primeiro bloco de conteúdo como texto, deve selecionar blocos de conteúdo pelo campo type em vez disso, e loops de uso de ferramentas devem devolver os blocos thinking completos e sem modificações junto com seus resultados de ferramentas (consulte Preservando blocos de pensamento). Tokens de pensamento são cobrados como tokens de saída mesmo quando o texto do pensamento não é retornado. Se você usava pensamento no Claude Sonnet 4.6 e exibe o texto de pensamento retornado, observe que thinking.display tinha como padrão "summarized" lá e tem como padrão "omitted" no Claude Sonnet 5; defina display: "summarized", como faz o exemplo a seguir, para continuar recebendo resumos legíveis (consulte Controlando a exibição do pensamento).

    client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    output_config={"effort": "high"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# A resposta contém blocos de pensamento resumidos e blocos de texto
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

  5. Parâmetros de amostragem removidos: Parâmetros de amostragem (temperature, top_p, top_k) definidos com um valor diferente do padrão não são aceitos e retornam um erro 400.

  6. Salvaguardas de cibersegurança: O Claude Sonnet 5 é o primeiro modelo da categoria Sonnet com salvaguardas de cibersegurança em tempo real. Requisições que envolvem tópicos de cibersegurança proibidos ou de alto risco podem ser recusadas. Recusas retornam como uma resposta HTTP 200 bem-sucedida com stop_reason: "refusal", não como um erro. Consulte Salvaguardas cibernéticas em tempo real no Claude Opus e Sonnet para saber o que as salvaguardas bloqueiam e como trabalhos legítimos de segurança podem se candidatar ao Cyber Verification Program.

Checklist de migração

  • Atualize o nome do modelo de claude-sonnet-4-6 para claude-sonnet-5.
  • Execute novamente a contagem de tokens no Claude Sonnet 5. O novo tokenizador produz aproximadamente 30% mais tokens para o mesmo texto, o que pode alterar o custo por requisição mesmo que o preço por token seja menor. O aumento exato depende do conteúdo e do formato da carga de trabalho.
  • Revise os limites de max_tokens dimensionados próximos ao comprimento de saída esperado e aumente-os até o máximo de 128k (inalterado em relação ao Claude Sonnet 4.6) quando útil.
  • Remova a configuração thinking: {type: "enabled", budget_tokens: N} (retorna um erro 400). O pensamento adaptativo está ativado por padrão; passe {type: "disabled"} para desativá-lo, ou use o parâmetro effort para controlar a profundidade.
  • Atualize o parsing de resposta que lê o conteúdo por posição, como content[0].text: com o pensamento ativado, blocos thinking chegam antes dos blocos text. Selecione blocos de conteúdo por type em vez disso, e devolva os blocos thinking sem modificações em loops de uso de ferramentas; blocos modificados retornam um erro 400.
  • Verifique se qualquer código que faz parsing do campo thinking o trata apenas como texto de exibição. thinking.display tem como padrão "omitted" no Claude Sonnet 5 (tinha como padrão "summarized" no Claude Sonnet 4.6), portanto blocos de pensamento chegam com um campo thinking vazio; defina display: "summarized" para receber resumos legíveis. Consulte Controlando a exibição do pensamento.
  • Remova os parâmetros temperature, top_p e top_k definidos com valores diferentes do padrão (eles retornam um erro 400 no Claude Sonnet 5).
  • Adicione tratamento para stop_reason: "refusal" se sua carga de trabalho puder tocar em tópicos de cibersegurança.
  • Refaça a linha de base de custo na sua carga de trabalho típica antes da implantação em produção.
  • Revise max_tokens para cargas de trabalho que anteriormente rodavam sem pensamento.

Migrando para o Claude Sonnet 5 a partir do Claude Sonnet 4.5 e modelos Sonnet anteriores

Se você está migrando do Claude Sonnet 4.5 ou de um modelo Sonnet anterior diretamente para o Claude Sonnet 5, aplique as mudanças de Migrando para o Claude Sonnet 5 a partir do Claude Sonnet 4.6 mais as mudanças desta seção.

Mudanças incompatíveis

Ao migrar do Sonnet 4.5

  1. O preenchimento prévio de mensagens do assistente não é mais suportado

    O preenchimento prévio de mensagens do assistente retorna um erro 400 no Claude Sonnet 4.6 e modelos posteriores, incluindo o Claude Sonnet 5. Use saídas estruturadas, instruções no prompt do sistema ou output_config.format em vez disso.

    Casos de uso comuns de preenchimento prévio e migrações:

    • Controlar a formatação da saída (forçar saída JSON/YAML): Use saídas estruturadas ou ferramentas com campos enum para tarefas de classificação.

    • Eliminar preâmbulos (remover frases como "Aqui está..."): Adicione instruções diretas no prompt do sistema: "Responda diretamente sem preâmbulo. Não comece com frases como 'Aqui está...', 'Com base em...', etc."

    • Evitar recusas indevidas: O Claude está muito melhor em recusas apropriadas agora. Um prompt claro na mensagem do usuário, sem preenchimento prévio, deve ser suficiente.

    • Continuações (retomar respostas interrompidas): Mova a continuação para a mensagem do usuário: "Sua resposta anterior foi interrompida e terminou com [previous_response]. Continue de onde parou."

    • Hidratação de contexto / consistência de papel (atualizar o contexto em conversas longas): Injete no turno do usuário o que antes eram lembretes preenchidos previamente como assistente.

  2. O escape de JSON em parâmetros de ferramentas pode diferir

    O escape de strings JSON em parâmetros de ferramentas pode diferir dos modelos anteriores. Parsers JSON padrão lidam com isso automaticamente, mas parsing personalizado baseado em strings pode precisar de atualizações.

Mudanças no pensamento estendido: Configurações de budget_tokens do Claude Sonnet 4.5 (thinking: {type: "enabled", budget_tokens: N}) não são suportadas no Claude Sonnet 5 e retornam um erro 400. O pensamento adaptativo está ativado por padrão, portanto a maioria das cargas de trabalho não precisa de nenhuma configuração thinking; use o parâmetro effort para controlar a profundidade do pensamento. Se você rodava o Claude Sonnet 4.5 sem pensamento estendido, passe thinking: {type: "disabled"} para preservar esse comportamento.

Ao migrar do Claude 3.x

  1. Remova os parâmetros de amostragem

    Parâmetros de amostragem (temperature, top_p, top_k) definidos com um valor diferente do padrão retornam um erro 400 no Claude Sonnet 5. Remova-os das requisições e use prompts para guiar o comportamento do modelo em vez disso.

  2. Atualize as versões das ferramentas

    Atualize para as versões mais recentes das ferramentas (text_editor_20250728, code_execution_20260521). Remova qualquer código que use o comando undo_edit.

  3. Trate o motivo de parada refusal

    Atualize sua aplicação para tratar motivos de parada refusal.

  4. Atualize seus prompts para mudanças comportamentais

    Os modelos Claude 4 têm um estilo de comunicação mais conciso e direto. Revise as melhores práticas de prompting para orientações de otimização.

Migrando para o Claude Sonnet 5 a partir do Claude Haiku 4.5

O Claude Haiku 4.5 e o Claude Sonnet 5 diferem mais no nível da API do que modelos adjacentes dentro de uma mesma classe: o Claude Haiku 4.5 usa pensamento estendido manual (desativado por padrão), uma janela de contexto de 200k tokens e até 64k tokens de saída, enquanto o Claude Sonnet 5 roda com pensamento adaptativo ativado por padrão, oferece uma janela de contexto de 1M de tokens por padrão e suporta até 128k tokens de saída.

Atualize o nome do seu modelo

model = "claude-haiku-4-5-20251001"  # Before
model = "claude-sonnet-5"  # After

O que mudou

  1. Configuração de pensamento: O Claude Haiku 4.5 suporta pensamento estendido manual (thinking: {type: "enabled", budget_tokens: N}) e rejeita thinking: {type: "adaptive"}. No Claude Sonnet 5, o suporte é invertido: o pensamento adaptativo está ativado por padrão, e o pensamento estendido manual retorna um erro 400. Remova as configurações thinking: {type: "enabled", budget_tokens: N} e confie no padrão, ou passe thinking: {type: "disabled"} para desativar o pensamento. budget_tokens não tem substituto direto; use o parâmetro effort para controlar a profundidade do pensamento. O effort não está disponível no Claude Haiku 4.5 e tem como padrão high no Claude Sonnet 5.

    O formato da resposta muda para ambos os tipos de requisição do Claude Haiku 4.5. Requisições que rodavam sem pensamento estendido agora podem retornar um ou mais blocos thinking antes do primeiro bloco text, portanto código que lê a resposta por posição, como content[0].text, deve selecionar blocos de conteúdo pelo campo type em vez disso, e loops de uso de ferramentas devem devolver os blocos thinking completos e sem modificações junto com seus resultados de ferramentas (consulte Preservando blocos de pensamento). Requisições que usavam pensamento estendido continuam recebendo blocos thinking, mas thinking.display tem como padrão "omitted" no Claude Sonnet 5 em vez de "summarized", portanto esses blocos chegam com um campo thinking vazio; defina display: "summarized" para continuar recebendo resumos legíveis (consulte Controlando a exibição do pensamento). Tokens de pensamento são cobrados como tokens de saída mesmo quando o texto do pensamento não é retornado.

  2. Parâmetros de amostragem removidos: temperature e top_p funcionam no Claude Haiku 4.5 (um de cada vez, não ambos). No Claude Sonnet 5, definir temperature, top_p ou top_k com um valor diferente do padrão retorna um erro 400. Remova esses parâmetros e use prompts para guiar o comportamento do modelo.

  3. Preenchimento prévio do assistente removido: Preencher previamente a mensagem do assistente funciona no Claude Haiku 4.5, mas retorna um erro 400 no Claude Sonnet 5. Use saídas estruturadas, instruções no prompt do sistema ou output_config.format em vez disso.

  4. Janela de contexto e saída maiores: O Claude Sonnet 5 oferece uma janela de contexto de 1M de tokens por padrão, acima dos 200k tokens do Claude Haiku 4.5, e suporta até 128k tokens de saída, acima dos 64k. O Claude Sonnet 5 também usa um tokenizador diferente, portanto execute novamente a contagem de tokens em vez de reutilizar contagens medidas no Claude Haiku 4.5.

  5. Preços: O Claude Haiku 4.5 tem preço de $1/$5 USD por milhão de tokens de entrada/saída. O Claude Sonnet 5 tem preço de $2/$10 USD por milhão de tokens de entrada/saída. Consulte Preços do Claude.

  6. Salvaguardas de cibersegurança: O Claude Sonnet 5 tem salvaguardas de cibersegurança em tempo real. Requisições que envolvem tópicos de cibersegurança proibidos ou de alto risco podem ser recusadas, retornadas como uma resposta HTTP 200 bem-sucedida com stop_reason: "refusal". Consulte Salvaguardas cibernéticas em tempo real no Claude Opus e Sonnet para saber o que as salvaguardas bloqueiam e como trabalhos legítimos de segurança podem se candidatar ao Cyber Verification Program.

Checklist de migração

  • Atualize o nome do modelo de claude-haiku-4-5-20251001 (ou o alias claude-haiku-4-5) para claude-sonnet-5.
  • Remova a configuração thinking: {type: "enabled", budget_tokens: N} (retorna um erro 400). O pensamento adaptativo está ativado por padrão; passe thinking: {type: "disabled"} para preservar o comportamento sem pensamento, e revise max_tokens para cargas de trabalho que rodavam sem pensamento.
  • Atualize o parsing de resposta que lê o conteúdo por posição, como content[0].text: com o pensamento ativado, blocos thinking chegam antes dos blocos text. Selecione blocos de conteúdo por type em vez disso, e devolva os blocos thinking sem modificações em loops de uso de ferramentas; blocos modificados retornam um erro 400.
  • Se sua UI exibe conteúdo de pensamento, defina display: "summarized". thinking.display tem como padrão "omitted" no Claude Sonnet 5, portanto, caso contrário, os blocos de pensamento chegam com um campo thinking vazio. Consulte Controlando a exibição do pensamento.
  • Use o parâmetro effort (padrão high) para controlar a profundidade do pensamento e o gasto de tokens; ele não está disponível no Claude Haiku 4.5, portanto nenhuma configuração existente é transferida.
  • Remova as configurações de temperature e top_p (valores diferentes do padrão retornam um erro 400 no Claude Sonnet 5).
  • Remova quaisquer preenchimentos prévios de mensagem do assistente (eles retornam um erro 400 no Claude Sonnet 5).
  • Execute novamente a contagem de tokens no Claude Sonnet 5 e revise os limites de max_tokens, que você pode aumentar até o máximo de 128k.
  • Adicione tratamento para stop_reason: "refusal" se sua carga de trabalho puder tocar em tópicos de cibersegurança.
  • Refaça a linha de base de custo na sua carga de trabalho típica antes da implantação em produção; o preço por token é diferente.

Was this page helpful?