Guia de migração

Guia para migrar para os modelos Claude mais recentes a partir de versões anteriores do Claude

Automatize sua migração com a skill da Claude API. No Claude Code, execute /claude-api migrate para invocar a skill da Claude API incluída. Ela funciona para qualquer modelo de destino nesta página:

/claude-api migrate this project to claude-opus-5

A skill aplica a troca do ID do modelo e, conforme necessário, alterações de parâmetros incompatíveis, substituição de prefill e calibração de effort para o seu modelo de destino em toda a sua base de código, e então produz uma lista de verificação de itens para verificar manualmente. Ela pede que você confirme o escopo da migração (diretório de trabalho inteiro, um subdiretório ou uma lista específica de arquivos) antes de editar qualquer arquivo. A skill também detecta clientes do Amazon Bedrock e da Claude Platform on AWS e ajusta os formatos de ID de modelo e as alterações de recursos para essas plataformas.

Migrando para Claude Mythos 5 e Claude Fable 5

Claude Fable 5 é o modelo mais capaz da Anthropic amplamente lançado, disponível de forma geral na Claude API, Amazon Bedrock, Claude Platform on AWS, Google Cloud e Microsoft Foundry. Claude Mythos 5 compartilha as mesmas capacidades e é oferecido com disponibilidade limitada a clientes aprovados no Project Glasswing.

As configurações básicas compartilhadas por claude-fable-5 e claude-mythos-5:

Thinking: O adaptive thinking (pensamento adaptativo) está sempre ativado. O modelo determina quando e quanto pensar em cada requisição, e nenhuma configuração de thinking é necessária. Tanto thinking: {type: "disabled"} quanto o pensamento estendido manual (thinking: {type: "enabled", budget_tokens: N}) retornam um erro 400.
Prefill: Pré-preencher a mensagem do assistente retorna um erro 400. Use instruções no prompt do sistema em vez disso.
Janela de contexto e saída: Uma janela de contexto de 1M de tokens por padrão, e até 128k tokens de saída por requisição.
Preços: US$ 10 por milhão de tokens de entrada e US$ 50 por milhão de tokens de saída. Consulte Preços do Claude.
Retenção de dados: Ambos os modelos exigem retenção de dados de 30 dias e não estão disponíveis sob acordos de "zero data retention" (retenção zero de dados), ou ZDR; ambos são designados como Covered Models. Na Claude API, uma requisição ao Claude Fable 5 de uma organização cuja configuração de retenção de dados não atende a esse requisito retorna um erro 400 invalid_request_error. Organizações com um acordo ZDR devem entrar em contato com sua equipe de conta da Anthropic para discutir a configuração de retenção de dados. Alternativamente, você pode configurar a retenção de dados por workspace. Consulte Requisitos de retenção de dados específicos por modelo para detalhes por plataforma.

Onde os dois modelos divergem:

Disponibilidade: Claude Fable 5 está disponível de forma geral. Claude Mythos 5 está disponível apenas para clientes aprovados no Project Glasswing.
Classificadores de segurança: Claude Fable 5 executa classificadores de segurança que podem recusar requisições com stop_reason: "refusal". Claude Mythos 5 não inclui esses classificadores. Consulte Recusas e fallback.
Priority Tier: O Priority Tier é suportado no Claude Fable 5, mas não no Claude Mythos 5.

Migrando para Claude Mythos 5 e Claude Fable 5 a partir do Claude Mythos Preview

Claude Mythos 5 é o sucessor com acesso restrito do Claude Mythos Preview, a prévia de pesquisa apenas por convite. Claude Fable 5 é o modelo disponível de forma geral com as mesmas capacidades, e as alterações nesta seção se aplicam igualmente a ambos os destinos.

A migração é, em grande parte, direta. Claude Mythos 5 e Claude Fable 5 usam a mesma Messages API e os mesmos padrões de uso de ferramentas que o Claude Mythos Preview, e as contagens de tokens permanecem praticamente inalteradas porque os três modelos usam o mesmo tokenizador. As principais alterações a verificar são os recursos que não estão mais disponíveis (listados na próxima seção) e a saída de thinking. Se você migrar para o Claude Fable 5, planeje também para recusas do classificador de segurança, que o Claude Mythos Preview e o Claude Mythos 5 não têm; consulte Recusas e fallback.

Para o cronograma de desativação do Claude Mythos Preview, consulte Descontinuações de modelos.

Atualize o nome do seu modelo

model = "claude-mythos-preview"  # Before
model = "claude-mythos-5"  # After

# Ou, para o modelo em disponibilidade geral com os mesmos recursos:
model = "claude-fable-5"  # After

Recursos não disponíveis no Claude Mythos 5 e Claude Fable 5

Pensamento estendido e orçamentos de tokens de thinking: O pensamento estendido manual (thinking: {type: "enabled", budget_tokens: N}) não é suportado em claude-mythos-5 ou claude-fable-5 e retorna um erro 400. O adaptive thinking está sempre ativado: o modelo determina quando e quanto pensar em cada requisição, e nenhuma configuração de thinking é necessária. thinking: {type: "disabled"} retorna um erro. budget_tokens não tem substituto direto: o thinking é adaptativo, e o parâmetro effort é um controle separado no nível de saída, não um orçamento de thinking.

Antes (Claude Mythos Preview):
client.messages.create( model="claude-mythos-preview", max_tokens=16000, thinking={"type": "enabled", "budget_tokens": 10000}, messages=[{"role": "user", "content": "..."}], )
Depois (Claude Mythos 5):
client.messages.create( model="claude-mythos-5", max_tokens=16000, messages=[{"role": "user", "content": "..."}], )
A alteração para o Claude Fable 5 é idêntica, com claude-fable-5 como nome do modelo.
Prefill do assistente: Pré-preencher a mensagem do assistente não é suportado em claude-mythos-5 ou claude-fable-5 e retorna um erro 400, o mesmo que no Claude Mythos Preview. Use instruções no prompt do sistema em vez disso.
Saída de thinking: Em claude-mythos-5 e claude-fable-5, a cadeia de pensamento bruta nunca é retornada, mas os blocos de thinking ainda carregam texto resumido legível quando thinking.display está definido como summarized. Passe os blocos de thinking de volta sem alterações ao continuar uma conversa no mesmo modelo. Consulte Saída de thinking no Claude Fable 5 e Claude Mythos 5.

Contagem de tokens e cobrança

claude-mythos-5 e claude-fable-5 usam o mesmo tokenizador que claude-mythos-preview (o tokenizador introduzido com o Claude Opus 4.7). As contagens de tokens permanecem praticamente inalteradas ao migrar de claude-mythos-preview. Em comparação com modelos anteriores ao Claude Opus 4.7, o mesmo conteúdo pode ser tokenizado em aproximadamente 30% mais tokens, variando conforme o conteúdo e o formato da carga de trabalho.

/v1/messages/count_tokens retorna valores praticamente inalterados para claude-mythos-5 e claude-fable-5 em comparação com claude-mythos-preview. Reestabeleça a linha de base de custo e latência nas suas próprias cargas de trabalho.

Lista de verificação de migração

Atualize o nome do modelo de claude-mythos-preview para claude-mythos-5, ou para claude-fable-5 para o modelo disponível de forma geral.
Remova a configuração de pensamento estendido manual (thinking: {type: "enabled", budget_tokens: N}). O adaptive thinking está sempre ativado, e nenhum campo thinking é necessário.
Remova qualquer configuração thinking: {type: "disabled"}. Desabilitar o thinking retorna um erro em claude-mythos-5 e claude-fable-5.
Remova budget_tokens. Ele não tem substituto direto: o thinking é adaptativo, e o parâmetro effort é um controle separado no nível de saída, não um orçamento de thinking.
Verifique se qualquer código que analisa o campo thinking o trata apenas como texto de exibição e passa os blocos de thinking de volta sem alterações ao continuar no mesmo modelo. thinking.display tem como padrão "omitted" em claude-mythos-5 e claude-fable-5, o mesmo que no Claude Mythos Preview; defina display: "summarized" para receber resumos legíveis. Consulte Saída de thinking no Claude Fable 5 e Claude Mythos 5.
Se você reproduzir o histórico de conversa em outro modelo, remova primeiro os blocos thinking e redacted_thinking dos turnos anteriores do assistente. Os blocos de thinking de claude-mythos-5 e claude-fable-5 estão vinculados ao modelo que os produziu, e modelos diferentes de Claude Fable 5 e Claude Mythos 5 os ignoram silenciosamente. Removê-los mantém as requisições entre modelos mínimas e uniformes.
Se você migrar para o Claude Fable 5, trate stop_reason: "refusal" e leia o campo stop_details.category. Claude Fable 5 executa classificadores de segurança que o Claude Mythos Preview e o Claude Mythos 5 não têm. Consulte Recusas e fallback.
Reestabeleça a linha de base de contagens de tokens e custos nas suas próprias cargas de trabalho. As contagens de tokens permanecem praticamente inalteradas ao migrar de claude-mythos-preview.

Migrando para Claude Mythos 5 e Claude Fable 5 a partir do Claude Opus 5

Claude Fable 5 e Claude Mythos 5 usam a mesma Messages API e os mesmos padrões de uso de ferramentas que o Claude Opus 5, com a mesma janela de contexto de 1M de tokens por padrão e os mesmos 128k tokens máximos de saída. As restrições de prefill e de parâmetros de amostragem, e o comportamento de exibição de thinking, são mantidos do Claude Opus 5 sem alterações. As alterações a verificar são o thinking sempre ativado, preços, Priority Tier e retenção de dados.

Atualize o nome do seu modelo

model = "claude-opus-5"  # Before
model = "claude-fable-5"  # After

# Ou, para o modelo Project Glasswing com as mesmas capacidades:
model = "claude-mythos-5"  # After

O que mudou

O thinking não pode mais ser desabilitado: No Claude Opus 5, o thinking está ativado por padrão e pode ser desligado com thinking: {type: "disabled"} em um nível de effort de high ou inferior. Em claude-fable-5 e claude-mythos-5, o adaptive thinking está sempre ativado, e thinking: {type: "disabled"} retorna um erro 400 em qualquer nível de effort. Remova a configuração thinking: {type: "disabled"} e use níveis de effort mais baixos para controlar o gasto de tokens em vez disso.
Preços: Claude Fable 5 e Claude Mythos 5 têm preço de US$ 10 por milhão de tokens de entrada e US$ 50 por milhão de tokens de saída, em comparação com US$ 5 e US$ 25 para o Claude Opus 5. Consulte Preços do Claude.
Priority Tier: O Priority Tier não é suportado no Claude Opus 5, então nenhum tráfego existente é afetado. Se sua organização tem um compromisso de Priority Tier, o Claude Fable 5 o suporta; o Claude Mythos 5 não.
Retenção de dados: Claude Fable 5 e Claude Mythos 5 exigem retenção de dados de 30 dias e não estão disponíveis sob acordos de "zero data retention" (ZDR); ambos são designados como Covered Models. Consulte Requisitos de retenção de dados específicos por modelo.

Lista de verificação de migração

Atualize o nome do modelo de claude-opus-5 para claude-fable-5 (ou claude-mythos-5).
Remova qualquer configuração thinking: {type: "disabled"}; ela retorna um erro 400 em claude-fable-5 e claude-mythos-5. Use níveis de effort mais baixos para controlar o gasto de tokens em vez disso, e revise max_tokens para cargas de trabalho que rodavam com thinking desabilitado no Claude Opus 5.
Se sua organização tem um acordo de "zero data retention" (ZDR), confirme a elegibilidade antes de migrar. Consulte Requisitos de retenção de dados específicos por modelo.
Reestabeleça a linha de base de custo nas suas próprias cargas de trabalho. As contagens de tokens permanecem praticamente inalteradas; o preço por token difere.

Migrando para Claude Mythos 5 e Claude Fable 5 a partir do Claude Opus 4.8

A migração é, em grande parte, direta. Claude Fable 5 e Claude Mythos 5 usam a mesma Messages API e os mesmos padrões de uso de ferramentas que o Claude Opus 4.8, com a mesma janela de contexto de 1M de tokens por padrão e os mesmos 128k tokens máximos de saída. As contagens de tokens permanecem praticamente inalteradas porque os modelos usam o mesmo tokenizador. As principais alterações a verificar são o adaptive thinking sempre ativado, a saída de thinking, as recusas do classificador de segurança (apenas Claude Fable 5) e os preços.

Atualize o nome do seu modelo

model = "claude-opus-4-8"  # Before
model = "claude-fable-5"  # After

# Ou, para o modelo Project Glasswing com as mesmas capacidades:
model = "claude-mythos-5"  # After

O que mudou

Os itens nesta seção descrevem as diferenças de API e comportamento que vale a pena verificar depois de trocar o ID do modelo. Exceto onde indicado, eles se aplicam igualmente a claude-fable-5 e claude-mythos-5.

O adaptive thinking está sempre ativado: O adaptive thinking é o único modo de thinking em claude-fable-5 e claude-mythos-5. O modelo determina quando e quanto pensar em cada requisição, e nenhuma configuração de thinking é necessária. thinking: {type: "disabled"} retorna um erro. Use o parâmetro effort para controlar a profundidade do thinking.

A mudança de comportamento a verificar: no Claude Opus 4.8, requisições sem um campo thinking rodam sem thinking; em claude-fable-5 e claude-mythos-5, essas mesmas requisições rodam com adaptive thinking. max_tokens continua sendo um limite rígido na saída total, thinking mais texto de resposta, então revise-o para cargas de trabalho que rodavam sem thinking no Claude Opus 4.8. Consulte Controle de custo.

Antes (Claude Opus 4.8):
client.messages.create( model="claude-opus-4-8", max_tokens=16000, thinking={"type": "adaptive"}, output_config={"effort": "high"}, messages=[{"role": "user", "content": "..."}], )
Depois (Claude Fable 5):
client.messages.create( model="claude-fable-5", max_tokens=16000, output_config={"effort": "high"}, messages=[{"role": "user", "content": "..."}], )
A alteração para o Claude Mythos 5 é idêntica, com claude-mythos-5 como nome do modelo.
Pensamento estendido e orçamentos de thinking (inalterado): O pensamento estendido manual (thinking: {type: "enabled", budget_tokens: N}) não é suportado em claude-fable-5 ou claude-mythos-5 e retorna um erro 400, o mesmo que no Claude Opus 4.8. budget_tokens não tem substituto direto: o thinking é adaptativo, e o parâmetro effort é um controle separado no nível de saída, não um orçamento de thinking.
Prefill do assistente (inalterado): Pré-preencher a mensagem do assistente não é suportado em claude-fable-5 ou claude-mythos-5 e retorna um erro 400, o mesmo que no Claude Opus 4.8. Use instruções no prompt do sistema em vez disso.
Saída de thinking: Em claude-fable-5 e claude-mythos-5, a cadeia de pensamento bruta nunca é retornada, mas os blocos de thinking ainda carregam texto resumido legível quando thinking.display está definido como summarized. Passe os blocos de thinking de volta sem alterações ao continuar uma conversa no mesmo modelo. Consulte Saída de thinking no Claude Fable 5 e Claude Mythos 5.
Classificadores de segurança e o stop reason refusal (apenas Claude Fable 5): claude-fable-5 executa classificadores de segurança nas requisições e durante a geração de resposta. Claude Mythos 5 não inclui esses classificadores. Quando um classificador recusa uma requisição, a Messages API retorna stop_reason: "refusal" como uma resposta HTTP 200 bem-sucedida, não um erro. O campo stop_details.category informa qual classificador foi acionado, com categorias como "cyber", "bio" e "reasoning_extraction", ou null quando a recusa não corresponde a nenhuma categoria nomeada. Consulte a tabela de categorias de recusa para o conjunto completo.

Você não é cobrado pelos tokens de entrada de uma requisição recusada antes de qualquer saída ser gerada. Quando um classificador é acionado no meio do stream, a entrada e a saída já transmitida são cobradas; descarte a saída parcial.

Para reexecutar requisições recusadas em outro modelo automaticamente, passe o parâmetro opt-in fallbacks, que está em beta na Claude API. O parâmetro não está disponível na Message Batches API ou no Amazon Bedrock, Google Cloud e Microsoft Foundry; nessas três plataformas, execute a nova tentativa no lado do cliente ou use o middleware de refusal-fallback do SDK. Consulte Recusas e fallback.
Comece com effort high: O padrão do parâmetro effort continua sendo high. No Claude Opus 4.8, a recomendação para programação e trabalho de alta autonomia é definir xhigh explicitamente. Em claude-fable-5 e claude-mythos-5, use high como padrão para a maioria das tarefas e reserve xhigh para as cargas de trabalho mais sensíveis à capacidade. Configurações de effort mais baixas ainda têm bom desempenho e frequentemente superam o desempenho de xhigh em modelos anteriores. Reduza o effort se uma tarefa for concluída, mas levar mais tempo do que o necessário. Consulte Prompting do Claude Fable 5.
Mínimo de cache de prompt mais baixo: O comprimento mínimo de prompt cacheável em claude-fable-5 e claude-mythos-5 é de 512 tokens, menor que os 1.024 tokens no Claude Opus 4.8. Prompts que eram curtos demais para cachear no Claude Opus 4.8 agora podem criar entradas de cache, sem necessidade de alterações no código. Consulte Cache de prompt para os mínimos por modelo.

Lista de verificação de migração

Se sua organização tem um acordo de "zero data retention" (ZDR), confirme a elegibilidade antes de migrar. claude-fable-5 e claude-mythos-5 exigem retenção de dados de 30 dias; na Claude API, requisições a claude-fable-5 que não atendem a esse requisito retornam um erro 400 invalid_request_error. Claude Opus 4.8 continua disponível sob ZDR. Consulte Requisitos de retenção de dados específicos por modelo.
Atualize o nome do modelo de claude-opus-4-8 para claude-fable-5 (ou claude-mythos-5).
Remova qualquer configuração thinking: {type: "disabled"}. Desabilitar o thinking retorna um erro em claude-fable-5 e claude-mythos-5, e requisições sem um campo thinking rodam com adaptive thinking.
Se você removeu o pensamento estendido manual e os prefills do assistente durante migrações anteriores, nenhuma ação é necessária: ambos continuam sem suporte em claude-fable-5 e claude-mythos-5.
Verifique se qualquer código que analisa o campo thinking o trata apenas como texto de exibição e passa os blocos de thinking de volta sem alterações ao continuar no mesmo modelo. thinking.display tem como padrão "omitted" em claude-fable-5 e claude-mythos-5, o mesmo que no Claude Opus 4.8; defina display: "summarized" para receber resumos legíveis. Consulte Saída de thinking no Claude Fable 5 e Claude Mythos 5.
Se você reproduzir o histórico de conversa em outro modelo, remova primeiro os blocos thinking e redacted_thinking dos turnos anteriores do assistente. Os blocos de thinking de claude-fable-5 e claude-mythos-5 estão vinculados ao modelo que os produziu, e modelos diferentes de Claude Fable 5 e Claude Mythos 5 os ignoram silenciosamente. Removê-los mantém as requisições entre modelos mínimas e uniformes. A exceção é resgatar um crédito de fallback, que exige o corpo da requisição ecoado sob as regras exatas desse recurso.
Se você migrar para o Claude Fable 5, trate stop_reason: "refusal" e leia o campo stop_details.category. Para reexecutar requisições recusadas em outro modelo automaticamente, considere o parâmetro opt-in fallbacks (beta). Consulte Recusas e fallback.
Reavalie sua configuração de effort. Comece com high para a maioria das tarefas, incluindo cargas de trabalho que rodavam em xhigh no Claude Opus 4.8.
Reestabeleça a linha de base de custo e latência nas suas próprias cargas de trabalho. As contagens de tokens permanecem praticamente inalteradas ao migrar de claude-opus-4-8; o preço por token difere.

Migrando para Claude Opus 5

Claude Opus 5 é uma melhoria significativa em relação ao Claude Opus 4.8, forte em raciocínio profundo, tarefas agênticas e de longo horizonte, e escalonamento de computação em tempo de teste. Para diferenças comportamentais e padrões de prompting específicos do modelo, consulte Prompting do Claude Opus 5.

Claude Opus 5 é uma atualização direta para o Claude Opus 4.8 com o mesmo preço de US$ 5 por milhão de tokens de entrada e US$ 25 por milhão de tokens de saída; consulte Preços do Claude. Há duas alterações incompatíveis para código já rodando no Claude Opus 4.8, abordadas em Alterações incompatíveis abaixo. Claude Opus 5 suporta o mesmo conjunto de recursos que o Claude Opus 4.8, incluindo a janela de contexto de 1M de tokens (o padrão, sem cabeçalho beta), 128k tokens máximos de saída, adaptive thinking, cache de prompt, processamento em lote, a Files API, suporte a PDF, visão e ferramentas do lado do servidor e do cliente, com duas exceções: web fetch não está disponível no Claude Opus 5, e o Priority Tier não é suportado no Claude Opus 5. Consulte cada página de ferramenta para disponibilidade por modelo.

Migrando para Claude Opus 5 a partir do Claude Opus 4.8

Atualize o nome do seu modelo

# Migração do Opus
model = "claude-opus-4-8"  # Before
model = "claude-opus-5"  # After

claude-opus-5 é um ID de modelo fixo sem sufixo de data, o mesmo esquema que claude-opus-4-8 e claude-sonnet-5.

Alterações incompatíveis

Thinking ativado por padrão: No Claude Opus 4.8, requisições sem um campo thinking rodam sem thinking; no Claude Opus 5, as mesmas requisições rodam com adaptive thinking. max_tokens continua sendo um limite rígido na saída total, thinking mais texto de resposta, então revise-o para cargas de trabalho que rodavam sem thinking no Claude Opus 4.8. Para preservar o comportamento antigo, passe thinking: {type: "disabled"}, sujeito ao limite de effort no próximo item; observe que com o thinking desabilitado o modelo pode ocasionalmente emitir chamadas de ferramentas como texto simples ou incluir tags XML internas em sua saída visível, então prefira níveis de effort mais baixos com thinking habilitado onde puder, e consulte Executando com thinking desabilitado para mitigações onde não puder.
Desabilitar o thinking é limitado ao effort high: Você ainda pode desligar o thinking com thinking: {type: "disabled"}, mas apenas em um nível de effort de high ou inferior. Uma requisição que combina thinking: {type: "disabled"} com effort xhigh ou max retorna um erro 400. Claude Opus 4.8 aceita essa combinação, então audite as requisições que desabilitam o thinking antes de migrar.

A verificação é aplicada em cada requisição: a configuração de effort e thinking de cada requisição é validada independentemente, então uma requisição que aumenta o effort para xhigh ou max enquanto o thinking está desabilitado é rejeitada mesmo se requisições anteriores na conversa foram aceitas.

Antes (aceito no Claude Opus 4.8, rejeitado no Claude Opus 5):
```
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)
```
Depois (Claude Opus 5), remova o campo thinking para reabilitar o thinking:
```
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    output_config={"effort": "xhigh"},  # thinking is on by default
    messages=[{"role": "user", "content": "..."}],
)
```
ou mantenha o thinking desabilitado e reduza o effort:
```
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "high"},  # or "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)
```

Alterações recomendadas

Estas não são obrigatórias, mas melhorarão sua experiência:

Teste o effort max para trabalho crítico de capacidade: Claude Opus 5 suporta o conjunto completo de níveis de effort (low, medium, high, xhigh, max). Onde a capacidade máxima importa mais do que o gasto de tokens, teste o effort max. Ele pode proporcionar ganhos nas tarefas mais exigentes, mas pode apresentar retornos decrescentes com o aumento do uso de tokens e pode ser propenso a pensar demais em tarefas mais simples. Se você rodar com effort xhigh ou max, defina um max_tokens grande para que o modelo tenha espaço para pensar e agir; comece com 64k tokens e ajuste a partir daí.
Considere fallbacks automáticos: Claude Opus 5 vem com classificadores de segurança de cibersegurança cujas recusas da categoria cyber podem fazer fallback para o Claude Opus 4.8. Para reexecutar requisições recusadas em outro modelo automaticamente, considere o parâmetro fallbacks com o modo "default" (fallbacks: "default"), que seleciona um modelo de fallback recomendado com base na categoria de recusa em vez de uma lista de modelos mantida manualmente. O fallback do lado do servidor está em beta; o modo "default" requer o cabeçalho beta server-side-fallback-2026-07-01. Consulte Recusas e fallback.
Cacheie prompts mais curtos: O comprimento mínimo de prompt cacheável no Claude Opus 5 é de 512 tokens, reduzido de 1.024 tokens no Claude Opus 4.8. Prompts que eram curtos demais para cachear no Claude Opus 4.8 agora podem criar entradas de cache, sem necessidade de alterações no código. Consulte Cache de prompt para os mínimos por modelo.
Altere ferramentas no meio da conversa (beta): Você pode adicionar ou remover ferramentas entre turnos de uma conversa sem invalidar acertos de cache de prompt em turnos anteriores. Envie o cabeçalho beta mid-conversation-tool-changes-2026-07-01. Isso é útil para cargas de trabalho agênticas que expõem ferramentas progressivamente ou as retiram conforme uma tarefa avança; sem ele, uma lista de ferramentas alterada invalida o prefixo cacheado.
Reajuste prompts de comprimento e verbosidade: Respostas visíveis padrão e entregáveis escritos são mais longos no Claude Opus 5 do que no Claude Opus 4.8, e reduzir o effort diminui o volume de thinking sem encurtar de forma confiável a resposta visível. Em vez disso, faça prompts explícitos para concisão ou um comprimento alvo. Consulte Comprimento e verbosidade da resposta e Comprimento de entregáveis escritos.
Remova instruções de verificação herdadas e restrinja o escopo: Claude Opus 5 verifica seu próprio trabalho sem ser instruído a fazê-lo, então remova instruções explícitas de verificação ou autoverificação herdadas de prompts ajustados para modelos anteriores; deixá-las causa verificação excessiva. Para tarefas restritas, limite o escopo da tarefa explicitamente. Em frameworks multiagente, dê orientação explícita sobre quais cenários justificam delegação ou limite o número de subagentes, porque o Claude Opus 5 delega mais prontamente do que modelos anteriores. Consulte Escopo da tarefa e verificação excessiva e Controlando a criação de subagentes.

Lista de verificação de migração

Atualize o nome do modelo de claude-opus-4-8 para claude-opus-5.
Revise cargas de trabalho que rodavam sem um campo thinking: elas rodam com thinking no Claude Opus 5. Revise max_tokens, que continua sendo um limite rígido na saída total (thinking mais texto de resposta), ou passe thinking: {type: "disabled"} com effort high ou inferior para preservar o comportamento antigo. Se você desabilitar o thinking, revise Executando com thinking desabilitado para os artefatos de saída que podem aparecer e suas mitigações de prompting.
Audite requisições que desabilitam o thinking: thinking: {type: "disabled"} com effort xhigh ou max retorna um erro 400, aplicado em cada requisição. Reabilite o thinking ou reduza o effort para high ou inferior.
Reavalie sua configuração de effort: execute uma nova varredura de effort nas suas próprias avaliações em vez de manter uma configuração ajustada para um modelo anterior. Vale a pena testar effort low e medium como controles de custo e latência, e teste o effort max onde a capacidade máxima importa mais do que o gasto de tokens. Se você rodar com effort xhigh ou max, aumente max_tokens para pelo menos 64k como ponto de partida.
Revise prompts próximos ao mínimo de cache: prompts de 512 tokens ou mais agora podem criar entradas de cache, reduzido de 1.024 tokens no Claude Opus 4.8.
Trate stop_reason: "refusal" e considere fallbacks: "default" (beta) para reexecutar requisições recusadas em um modelo de fallback recomendado automaticamente.
Se sua organização tem um compromisso de Priority Tier, planeje a capacidade separadamente: o Priority Tier não é suportado no Claude Opus 5, enquanto o Claude Opus 4.8 o mantém.
Para cargas de trabalho agênticas, considere orçamentos de tarefa (beta) e alterações de ferramentas no meio da conversa (beta).
Reajuste prompts de comprimento e verbosidade: respostas visíveis padrão e entregáveis escritos são mais longos no Claude Opus 5, e reduzir o effort diminui o volume de thinking sem encurtar de forma confiável a resposta visível. Faça prompts explícitos para concisão ou um comprimento alvo. Consulte Comprimento e verbosidade da resposta e Comprimento de entregáveis escritos.
Remova instruções de verificação e autoverificação herdadas de prompts ajustados para modelos anteriores (elas causam verificação excessiva no Claude Opus 5), restrinja o escopo da tarefa explicitamente para tarefas restritas e, em frameworks multiagente, direcione ou limite a delegação de subagentes. Consulte Escopo da tarefa e verificação excessiva e Controlando a criação de subagentes.
Reestabeleça a linha de base de custo e latência nas suas próprias cargas de trabalho.

Migrando para o Claude Opus 5 a partir do Claude Opus 4.7

O Claude Opus 5 deve ter um desempenho sólido e imediato em prompts e avaliações existentes do Claude Opus 4.7, com o mesmo preço de US$ 5 por milhão de tokens de entrada e US$ 25 por milhão de tokens de saída. Ele oferece suporte ao mesmo conjunto de recursos que o Claude Opus 4.7, incluindo a janela de contexto de 1M de tokens, 128k de tokens máximos de saída, pensamento adaptativo, cache de prompt, processamento em lote, a Files API, suporte a PDF, visão e ferramentas do lado do servidor e do lado do cliente, com duas exceções: web fetch não está disponível no Claude Opus 5, e Priority Tier não é compatível com o Claude Opus 5. Ele também adiciona mensagens de sistema no meio da conversa e documenta publicamente os detalhes de parada por recusa.

Atualize o nome do seu modelo

# Migração do Opus
model = "claude-opus-4-7"  # Before
model = "claude-opus-5"  # After

Mudanças incompatíveis

Pensamento ativado por padrão: No Claude Opus 4.7, requisições sem um campo thinking são executadas sem pensamento; no Claude Opus 5, as mesmas requisições são executadas com pensamento adaptativo. max_tokens continua sendo um limite rígido na saída total, pensamento mais texto de resposta, então reavalie-o para cargas de trabalho que eram executadas sem pensamento no Claude Opus 4.7. Para preservar o comportamento antigo, passe thinking: {type: "disabled"}, sujeito ao limite de esforço no próximo item; observe que, com o pensamento desativado, o modelo pode ocasionalmente emitir chamadas de ferramentas como texto simples ou incluir tags XML internas em sua saída visível, então prefira níveis de esforço mais baixos com o pensamento ativado quando possível, e consulte Executando com o pensamento desativado para mitigações quando não for possível.
Desativar o pensamento é limitado ao esforço high: Você pode desativar o pensamento com thinking: {type: "disabled"}, mas apenas em um nível de esforço de high ou inferior. Uma requisição que combina thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400. O Claude Opus 4.7 aceita essa combinação, então audite as requisições que desativam o pensamento antes de migrar.

A verificação é aplicada em cada requisição: a configuração de esforço e pensamento de cada requisição é validada de forma independente, então uma requisição que eleva o esforço para xhigh ou max enquanto o pensamento está desativado é rejeitada mesmo que requisições anteriores na conversa tenham sido aceitas.

Antes (aceito no Claude Opus 4.7, rejeitado no Claude Opus 5):
```
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)
```
Depois (Claude Opus 5), remova o campo thinking para executar com pensamento:
```
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    output_config={"effort": "xhigh"},  # thinking is on by default
    messages=[{"role": "user", "content": "..."}],
)
```
ou mantenha o pensamento desativado e reduza o esforço:
```
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "high"},  # or "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)
```

O que mudou

Os itens a seguir não são mudanças incompatíveis; eles descrevem diferenças de comportamento que vale a pena verificar depois de trocar o ID do modelo.

Parâmetros de amostragem (inalterados): Definir temperature, top_p ou top_k com um valor não padrão retorna um erro 400 no Claude Opus 5, assim como no Claude Opus 4.7. Os tipos de requisição do SDK ainda definem esses campos para compatibilidade com modelos anteriores, então o código que os define passa na verificação de tipos, mas a API rejeita a requisição no lado do servidor. Se você removeu esses parâmetros ao migrar para o Opus 4.7, nenhuma alteração adicional é necessária.
O padrão de esforço é high: O padrão do parâmetro de esforço no Claude Opus 5 é high na Claude API e no Claude Code. Se você já define o esforço explicitamente, sua configuração permanece inalterada.
Níveis de esforço recalibrados: A alocação de tokens por trás de cada nível de esforço muda no Claude Opus 5 em comparação com o Claude Opus 4.7, e o Claude Opus 5 oferece suporte ao conjunto completo de níveis de esforço (low, medium, high, xhigh, max). Execute uma nova varredura de esforço em suas próprias avaliações em vez de reaproveitar uma configuração ajustada para o Claude Opus 4.7. Vale a pena testar os esforços low e medium como controles de custo e latência, e teste o esforço max onde a capacidade máxima importa mais do que o gasto de tokens. Se você executar com esforço xhigh ou max, defina um max_tokens grande para que o modelo tenha espaço para pensar e agir; comece com 64k tokens e ajuste a partir daí. Consulte Esforço.
A janela de contexto de 1M é o padrão: O Claude Opus 5 fornece a janela de contexto completa de 1M de tokens por padrão, sem cabeçalho beta e sem custo adicional de contexto longo. Se o seu cliente passa um cabeçalho beta de janela de contexto para compatibilidade com modelos mais antigos, você pode removê-lo no Claude Opus 5.
Mensagens de sistema no meio da conversa: O Claude Opus 5 aceita mensagens com role: "system" imediatamente após um turno do usuário no array messages (sujeito às regras de posicionamento). Use o campo system de nível superior para instruções que se aplicam desde o início. O Claude Opus 4.7 rejeita role: "system" em messages com um erro 400. Se você mantém caminhos de código que reconstroem o histórico completo de mensagens para atualizar instruções, pode simplificá-los e preservar os acertos de cache de prompt em turnos anteriores.
Detalhes de parada por recusa: O objeto stop_details em respostas de recusa (disponível desde o Claude Opus 4.7) agora está documentado publicamente. Quando o modelo recusa uma requisição, ele identifica a categoria da recusa, além do motivo de parada refusal existente. Nenhum cabeçalho beta é necessário, e não há como desativar. Consulte Tratamento de motivos de parada.
Mínimo menor para cache de prompt: O comprimento mínimo de prompt armazenável em cache no Claude Opus 5 é de 512 tokens, menor do que no Claude Opus 4.7. Prompts que eram curtos demais para serem armazenados em cache no Claude Opus 4.7 agora podem criar entradas de cache, sem necessidade de alterações no código. Consulte Cache de prompt para os mínimos por modelo.
Modo rápido: O Claude Opus 5 oferece suporte ao modo rápido (prévia de pesquisa); o modo rápido não está disponível no Claude Opus 4.7, onde requisições com speed: "fast" retornam um erro. O parâmetro speed: "fast" e o cabeçalho beta fast-mode-2026-02-01 funcionam sem alterações no Claude Opus 5.

Mudanças recomendadas

Estas não são obrigatórias, mas melhorarão sua experiência:

Considere fallbacks automáticos: O Claude Opus 5 vem com classificadores de segurança de cibersegurança cujas recusas da categoria cibernética podem recorrer ao Claude Opus 4.8 como fallback. Para reexecutar automaticamente requisições recusadas em outro modelo, considere o parâmetro fallbacks com o modo "default" (fallbacks: "default"), que seleciona um modelo de fallback recomendado com base na categoria de recusa em vez de uma lista de modelos mantida manualmente. O fallback do lado do servidor está em beta; o modo "default" requer o cabeçalho beta server-side-fallback-2026-07-01. Consulte Recusas e fallback.
Alterar ferramentas no meio da conversa (beta): Você pode adicionar ou remover ferramentas entre turnos de uma conversa sem invalidar os acertos de cache de prompt em turnos anteriores. Envie o cabeçalho beta mid-conversation-tool-changes-2026-07-01. Isso é útil para cargas de trabalho agênticas que expõem ferramentas progressivamente ou as retiram conforme uma tarefa avança; sem isso, uma lista de ferramentas alterada invalida o prefixo em cache.
Reajuste prompts de comprimento e verbosidade: Respostas visíveis padrão e entregáveis escritos são mais longos no Claude Opus 5 do que em modelos Opus anteriores, e reduzir o esforço diminui o volume de pensamento sem encurtar de forma confiável a resposta visível. Em vez disso, solicite explicitamente concisão ou um comprimento-alvo no prompt. Consulte Comprimento e verbosidade da resposta e Comprimento de entregáveis escritos.
Remova instruções de verificação herdadas e restrinja o escopo: O Claude Opus 5 verifica seu próprio trabalho sem que seja solicitado, então remova instruções explícitas de verificação ou autoverificação herdadas de prompts ajustados para modelos anteriores; deixá-las causa verificação excessiva. Para tarefas restritas, limite o escopo da tarefa explicitamente. Em frameworks multiagente, forneça orientação explícita sobre quais cenários justificam delegação ou limite o número de subagentes, porque o Claude Opus 5 delega com mais facilidade do que modelos anteriores. Consulte Escopo da tarefa e verificação excessiva e Controlando a criação de subagentes.

Checklist de migração

Atualize o nome do modelo de claude-opus-4-7 para claude-opus-5 (ou atualize os aliases).
Revise cargas de trabalho que eram executadas sem um campo thinking: elas são executadas com pensamento no Claude Opus 5. Reavalie max_tokens, que continua sendo um limite rígido na saída total (pensamento mais texto de resposta), ou passe thinking: {type: "disabled"} com esforço high ou inferior para preservar o comportamento antigo. Se você desativar o pensamento, revise Executando com o pensamento desativado para os artefatos de saída que podem aparecer e suas mitigações via prompt.
Audite requisições que desativam o pensamento: thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400, aplicado em cada requisição. Reative o pensamento ou reduza o esforço para high ou inferior.
Se você removeu parâmetros de amostragem durante a migração para o Opus 4.7, nenhuma ação é necessária. Se você os adicionou novamente com um caminho de nova tentativa em caso de 400, remova esse caminho de nova tentativa.
Reavalie sua configuração de effort: execute uma nova varredura de esforço em suas próprias avaliações em vez de reaproveitar uma configuração ajustada para o Claude Opus 4.7. Teste os esforços low e medium como controles de custo e latência, e o esforço max onde a capacidade máxima importa mais do que o gasto de tokens. Se você executar com esforço xhigh ou max, aumente max_tokens para pelo menos 64k como ponto de partida.
Remova qualquer cabeçalho beta de janela de contexto. A janela de contexto de 1M é o padrão na Claude API, Amazon Bedrock, Google Cloud e Microsoft Foundry.
Se você reconstrói o histórico da conversa para atualizar instruções, considere mudar para uma mensagem de sistema no meio da conversa para preservar os acertos de cache de prompt.
Verifique se o seu tratamento de motivos de parada lê stop_details em recusas (disponível desde o Claude Opus 4.7; agora documentado publicamente), e considere fallbacks: "default" (beta) para reexecutar automaticamente requisições recusadas em um modelo de fallback recomendado.
Revise prompts próximos ao mínimo de cache: prompts de 512 tokens ou mais agora podem criar entradas de cache.
Se você usa web fetch, planeje uma alternativa: ele não está disponível no Claude Opus 5.
Se sua organização tem um compromisso de Priority Tier, observe que o Priority Tier não é compatível com o Claude Opus 5.
Se você usava o modo rápido no Claude Opus 4.7, nenhuma alteração de requisição é necessária além do ID do modelo: speed: "fast" e o cabeçalho beta fast-mode-2026-02-01 funcionam sem alterações no Claude Opus 5.
Para cargas de trabalho agênticas, considere orçamentos de tarefa (beta) e alterações de ferramentas no meio da conversa (beta).
Reajuste prompts de comprimento e verbosidade, e remova instruções de verificação e autoverificação herdadas de prompts ajustados para modelos anteriores.
Refaça a linha de base de custo e latência no nível de esforço escolhido.

Migrando para o Claude Opus 5 a partir do Claude Opus 4.6 e modelos Opus anteriores

O Claude Opus 5 deve apresentar um desempenho sólido e imediato em prompts e avaliações existentes do Claude Opus 4.6 com o mesmo preço, mas há algumas mudanças comportamentais e de API que vale a pena conhecer ao migrar. A maioria dessas mudanças entrou em vigor no Claude Opus 4.7; duas outras, pensamento ativado por padrão e um limite de esforço ao desativar o pensamento, entram em vigor no Claude Opus 5. Todas elas são abordadas abaixo, então esta seção é completa para código vindo diretamente do Claude Opus 4.6. O Claude Opus 5 oferece suporte ao mesmo conjunto de recursos que o Claude Opus 4.6, incluindo:

Janela de contexto de 1M de tokens com preço padrão da API, sem cobrança adicional por contexto longo
128k de tokens máximos de saída
Pensamento adaptativo
Cache de prompt
Processamento em lote
Files API
Suporte a PDF
Visão
Ferramentas do lado do servidor e do lado do cliente (bash, execução de código, uso de computador, editor de texto, busca na web, conector MCP, memória)

Duas exceções: web fetch não está disponível no Claude Opus 5, e Priority Tier não é compatível com o Claude Opus 5.

Atualize o nome do seu modelo

# Migração do Opus
model = "claude-opus-4-6"  # Before
model = "claude-opus-5"  # After

Mudanças incompatíveis

Pensamento estendido removido: thinking: {type: "enabled", budget_tokens: N} não é mais compatível com o Claude Opus 4.7 ou modelos posteriores e retorna um erro 400. Mude para pensamento adaptativo (thinking: {type: "adaptive"}) e use o parâmetro de esforço para controlar a profundidade do pensamento. No Claude Opus 5, o pensamento adaptativo está ativado por padrão: thinking: {type: "adaptive"} é válido e equivalente a omitir o campo thinking completamente (veja o próximo item).

Antes (Claude Opus 4.6):
client.messages.create( model="claude-opus-4-6", max_tokens=16000, thinking={"type": "enabled", "budget_tokens": 10000}, messages=[{"role": "user", "content": "..."}], )
Depois (Claude Opus 5):
client.messages.create( model="claude-opus-5", max_tokens=16000, thinking={"type": "adaptive"}, output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low" messages=[{"role": "user", "content": "..."}], )
O pensamento adaptativo pode ser direcionado por meio de prompts e do parâmetro de esforço; consulte Escolhendo um nível de esforço.
Pensamento ativado por padrão: No Claude Opus 4.6 e no Claude Opus 4.7, requisições sem um campo thinking são executadas sem pensamento; no Claude Opus 5, as mesmas requisições são executadas com pensamento adaptativo. max_tokens continua sendo um limite rígido na saída total, pensamento mais texto de resposta, então revise-o para cargas de trabalho que eram executadas sem pensamento. Para preservar o comportamento antigo, passe thinking: {type: "disabled"}, sujeito ao limite de esforço no próximo item; observe que, com o pensamento desativado, o modelo pode ocasionalmente emitir chamadas de ferramentas como texto simples ou incluir tags XML internas em sua saída visível, então prefira níveis de esforço mais baixos com o pensamento ativado quando possível, e consulte Executando com o pensamento desativado para mitigações quando não for possível.
Desativar o pensamento é limitado ao esforço high: Você pode desativar o pensamento com thinking: {type: "disabled"}, mas apenas em um nível de esforço de high ou inferior. Uma requisição que combina thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400 no Claude Opus 5, aplicado em cada requisição. Audite as requisições que desativam o pensamento antes de migrar: reative o pensamento ou reduza o esforço para high ou inferior.
Parâmetros de amostragem removidos: Definir temperature, top_p ou top_k para qualquer valor não padrão no Claude Opus 4.7 ou modelos posteriores, incluindo o Claude Opus 5, retorna um erro 400. O caminho de migração mais seguro é omitir esses parâmetros completamente dos payloads de requisição. O uso de prompts é a forma recomendada de orientar o comportamento do modelo no Claude Opus 5. Se você estava usando temperature = 0 para determinismo, observe que isso nunca garantiu saídas idênticas em modelos anteriores.
Conteúdo de pensamento omitido por padrão: Os blocos de pensamento ainda aparecem no fluxo de resposta no Claude Opus 4.7 e modelos posteriores, mas o campo thinking deles fica vazio, a menos que você opte explicitamente por exibi-lo. Esta é uma mudança silenciosa em relação ao Claude Opus 4.6, onde o padrão era retornar texto de pensamento resumido. Para restaurar o conteúdo de pensamento resumido, defina thinking.display como "summarized":
thinking = { "type": "adaptive", "display": "summarized", }
O padrão é "omitted" no Claude Opus 4.7 e modelos posteriores. Se o seu produto transmite o raciocínio aos usuários via streaming, o novo padrão aparece como uma longa pausa antes do início da saída; defina display: "summarized" para restaurar o progresso visível durante o pensamento. Consulte Controlando a exibição do pensamento para obter detalhes.
Contagem de tokens atualizada: O Claude Opus 4.7 introduziu um novo tokenizador, que os modelos Opus posteriores, incluindo o Claude Opus 5, também usam. Ele contribui para um desempenho aprimorado em uma ampla gama de tarefas e pode usar aproximadamente de 1x a 1,35x mais tokens ao processar texto em comparação com modelos anteriores ao Claude Opus 4.7 (até ~35% a mais, variando conforme o conteúdo).

/v1/messages/count_tokens retorna um número diferente de tokens para o Claude Opus 5 em comparação com o Claude Opus 4.6. A eficiência de tokens pode variar conforme o formato da carga de trabalho.

Intervenções de prompt, task_budget e effort podem ajudar a controlar custos e garantir o uso apropriado de tokens. Esses controles podem implicar uma troca em relação à inteligência do modelo. Atualize seus parâmetros max_tokens para dar margem adicional, incluindo gatilhos de compactação. O Claude Opus 5 fornece uma janela de contexto de 1M com preço padrão da API, sem cobrança adicional por contexto longo.
Remoção de prefill (herdada do Opus 4.6): Pré-preencher mensagens do assistente retorna um erro 400 no Claude Opus 4.7 e modelos posteriores, incluindo o Claude Opus 5. Use saídas estruturadas, instruções no prompt do sistema ou output_config.format em vez disso.

Escolhendo um nível de esforço

O parâmetro de esforço permite ajustar a inteligência do Claude em relação ao gasto de tokens, trocando capacidade por maior velocidade e custos mais baixos. O Claude Opus 5 oferece suporte ao conjunto completo de níveis de esforço e tem high como padrão. Execute uma nova varredura de esforço em suas próprias avaliações em vez de reutilizar uma configuração ajustada para um modelo anterior:

max: Pode proporcionar ganhos nas tarefas mais exigentes, mas pode apresentar retornos decrescentes devido ao aumento do uso de tokens e pode ser propenso a pensar demais em tarefas mais simples. Teste-o onde a capacidade máxima importa mais do que o gasto de tokens.
xhigh: Capacidade estendida para trabalho agêntico e de codificação de longa duração que precisa de mais profundidade do que o padrão.
high: O padrão. Equilibra o uso de tokens e a inteligência para a maioria das tarefas.
medium: Redução de custo em relação ao padrão, vale a pena testar como controle de custo e latência.
low: Mais eficiente. Reserve para tarefas curtas e delimitadas e cargas de trabalho sensíveis à latência.

Se você executar com esforço xhigh ou max, defina um max_tokens grande para que o modelo tenha espaço para pensar e agir; comece com 64k tokens e ajuste a partir daí. O esforço é mais importante para este modelo do que para qualquer Opus anterior. Experimente ativamente com ele ao fazer o upgrade.

Mudanças de comportamento

O Claude Opus 4.7 introduziu várias diferenças comportamentais em relação ao Claude Opus 4.6 que não são mudanças incompatíveis de API, mas podem exigir atualizações de prompt ou remoção de scaffolding. Elas se mantêm no Claude Opus 5, com os ajustes observados abaixo.

O comprimento da resposta varia conforme o caso de uso: O Claude Opus 4.7 calibra o comprimento da resposta de acordo com a complexidade que julga que a tarefa tem, em vez de usar uma verbosidade fixa por padrão. Isso geralmente significa respostas mais curtas em consultas simples e muito mais longas em análises abertas.

Se o seu produto depende de um determinado estilo ou verbosidade de saída, pode ser necessário ajustar seus prompts. Por exemplo, para diminuir a verbosidade, adicione: "Forneça respostas concisas e focadas. Pule contexto não essencial e mantenha os exemplos mínimos." Se você observar tipos específicos de explicação excessiva, adicione instruções direcionadas no seu prompt para evitá-los.

Exemplos positivos mostrando como o Claude pode se comunicar com o nível apropriado de concisão tendem a ser mais eficazes do que exemplos negativos ou instruções que dizem ao modelo o que não fazer. No Claude Opus 5, as respostas visíveis padrão e os entregáveis escritos são mais longos do que em modelos Opus anteriores, e reduzir o esforço diminui o volume de pensamento sem encurtar de forma confiável a resposta visível; peça explicitamente concisão ou um comprimento-alvo no prompt. Consulte Comprimento da resposta e verbosidade.
Seguimento de instruções mais literal: O Claude Opus 4.7 interpreta prompts de forma mais literal e explícita do que o Claude Opus 4.6, particularmente em níveis de esforço mais baixos. Ele não generaliza silenciosamente uma instrução de um item para outro e não infere solicitações que você não fez. A vantagem desse literalismo é precisão e menos retrabalho. Ele geralmente tem melhor desempenho em casos de uso de API com prompts cuidadosamente ajustados, extração estruturada e pipelines onde você deseja comportamento previsível. Uma revisão de prompts e do harness pode ser especialmente útil para a migração para o Claude Opus 5.
Tom mais direto: Como em qualquer novo modelo, o estilo de prosa em escrita longa pode mudar. O Claude Opus 4.7 é mais direto e opinativo, com menos frases de validação e menos emojis do que o estilo mais caloroso do Claude Opus 4.6. Se o seu produto depende de uma voz específica, reavalie os prompts de estilo em relação à nova linha de base.
Atualizações de progresso integradas em traces agênticos: O Claude Opus 4.7 fornece atualizações mais regulares e de maior qualidade ao usuário ao longo de traces agênticos longos. Se você adicionou scaffolding para forçar mensagens de status intermediárias ("Após cada 3 chamadas de ferramenta, resuma o progresso"), tente removê-lo. Se você achar que o comprimento ou o conteúdo das atualizações voltadas ao usuário do Claude Opus 4.7 não estão bem calibrados para o seu caso de uso, descreva explicitamente como essas atualizações devem ser no prompt e forneça exemplos.
Criação de subagentes alterada: O Claude Opus 4.7 tende a criar menos subagentes por padrão do que o Claude Opus 4.6, enquanto o Claude Opus 5 delega a subagentes com mais facilidade do que modelos anteriores. O comportamento pode ser direcionado por meio de prompts em qualquer direção; dê orientação explícita sobre quando subagentes são desejáveis ou limite o número de subagentes. Consulte Controlando a criação de subagentes.
Calibração de esforço mais rigorosa: Mudando significativamente em relação ao Claude Opus 4.6, o Claude Opus 4.7 respeita os níveis de esforço de forma rigorosa, especialmente na extremidade inferior. Em low e medium, o modelo limita seu trabalho ao que foi solicitado, em vez de fazer mais do que o pedido.

Isso é bom para latência e custo, mas em tarefas moderadamente complexas executadas com esforço low há algum risco de pensamento insuficiente. Se você observar raciocínio superficial em problemas complexos, aumente o esforço para high ou xhigh em vez de contornar isso com prompts.

Se você precisar manter o esforço em low por questões de latência, adicione orientação direcionada: "Esta tarefa envolve raciocínio em várias etapas. Pense cuidadosamente sobre o problema antes de responder." Consulte Níveis de esforço recomendados para o Claude Opus 4.7.
Menos chamadas de ferramentas por padrão: O Claude Opus 4.7 tem uma tendência a usar ferramentas com menos frequência do que o Claude Opus 4.6 e a usar mais raciocínio. Isso produz melhores resultados na maioria dos casos.

Para aumentar o uso de ferramentas, aumente a configuração de esforço. As configurações de esforço high ou xhigh mostram substancialmente mais uso de ferramentas em busca agêntica e codificação. Você também pode ajustar seu prompt para instruir explicitamente o modelo sobre quando e como usar adequadamente suas ferramentas.
Salvaguardas de cibersegurança em tempo real: Recém-adicionadas no Claude Opus 4.7, requisições que envolvem tópicos proibidos ou de alto risco podem levar a recusas. Para trabalho de segurança legítimo, como testes de penetração, pesquisa de vulnerabilidades ou red-teaming, inscreva-se no Cyber Verification Program para solicitar restrições reduzidas. Consulte Salvaguardas, avisos e recursos para contexto.
Suporte a imagens de alta resolução: O Claude Opus 4.7 é o primeiro modelo Claude com suporte a imagens de alta resolução. A resolução máxima de imagem é de 2.576 pixels na borda mais longa, acima dos 1.568 pixels em modelos anteriores. Isso desbloqueia ganhos em cargas de trabalho com uso intensivo de visão e é particularmente valioso para uso de computador, compreensão de capturas de tela e análise de documentos.

O suporte a alta resolução é automático e não requer cabeçalho beta nem opt-in do lado do cliente. Duas coisas a planejar:
- Imagens em resolução total podem usar até aproximadamente 3x mais tokens de imagem do que em modelos anteriores (até 4.784 tokens por imagem, em comparação com o limite anterior de aproximadamente 1.600 tokens por imagem). Reorce o orçamento de max_tokens e as expectativas de custo para cargas de trabalho com muitas imagens, ou reduza a resolução antes de enviar se você não precisar da fidelidade adicional.
- As coordenadas de apontamento e de bounding box retornadas pelo modelo são 1:1 com os pixels reais da imagem no Claude Opus 4.7, então nenhuma conversão de fator de escala é necessária.
Consulte Suporte a imagens de alta resolução no Claude Opus 4.7 para obter detalhes.

Mudanças recomendadas

Estas não são obrigatórias, mas melhorarão sua experiência:

Reavalie max_tokens: Como o mesmo texto produz uma contagem de tokens maior no Claude Opus 4.7 e modelos posteriores, atualize seus parâmetros max_tokens para dar margem adicional, incluindo gatilhos de compactação. Intervenções de prompt, task_budget e effort podem ajudar a controlar custos e garantir o uso apropriado de tokens.
Audite as expectativas de contagem de tokens: Qualquer caminho de código que estima tokens no lado do cliente ou assume uma proporção fixa de token para caractere deve ser retestado com o Claude Opus 5. Use o endpoint de contagem de tokens para verificar.
Adote orçamentos de tarefa (beta): O Claude Opus 4.7 introduz orçamentos de tarefa. Esses orçamentos permitem informar ao Claude quantos tokens ele tem para um loop agêntico completo, incluindo pensamento, chamadas de ferramentas, resultados de ferramentas e saída final. O modelo vê uma contagem regressiva em execução e a usa para priorizar o trabalho e concluir a tarefa de forma elegante à medida que o orçamento é consumido. Para usar, defina o cabeçalho beta task-budgets-2026-03-13 e adicione o seguinte à sua configuração de saída:
output_config = { "effort": "high", "task_budget": {"type": "tokens", "total": 128000}, }
Pode ser necessário experimentar diferentes orçamentos de tarefa para o seu caso de uso. Se o modelo receber um orçamento de tarefa muito restritivo, ele pode concluir a tarefa de forma menos completa, referenciando seu orçamento como a restrição.

Para tarefas agênticas abertas onde a qualidade importa mais do que a velocidade, não defina um orçamento de tarefa. Reserve orçamentos de tarefa para cargas de trabalho onde você precisa que o modelo limite seu trabalho a uma cota de tokens. O valor mínimo para um orçamento de tarefa é 20k tokens.

Um orçamento de tarefa não é um limite rígido; é uma sugestão da qual o modelo tem conhecimento. Ele difere de max_tokens:
- task_budget: um limite consultivo em todo o loop agêntico completo. O modelo o vê e o usa para regular seu ritmo.
- max_tokens: um teto rígido por requisição sobre tokens gerados. Não é passado ao modelo, então o modelo não tem conhecimento dele.
Use task_budget quando quiser que o modelo se automodere, e max_tokens como um teto rígido para limitar o uso.
Defina um max_tokens grande com esforço max ou xhigh: Se você estiver executando o Claude Opus 4.7 ou um modelo posterior com esforço max ou xhigh, defina um orçamento grande de tokens máximos de saída para que o modelo tenha espaço para pensar e agir em seus subagentes e chamadas de ferramentas. Comece com 64k tokens e ajuste a partir daí.
Reduza a resolução das imagens se a alta resolução for desnecessária: O Claude Opus 4.7 e modelos posteriores oferecem suporte a imagens de até 2576px / 3,75MP. Imagens de alta resolução usam mais tokens. Se a fidelidade adicional da imagem for desnecessária, reduza a resolução das imagens antes de enviar ao Claude para evitar aumentos no uso de tokens. Consulte Imagens e visão.
Considere fallbacks automáticos: O Claude Opus 5 vem com classificadores de segurança de cibersegurança cujas recusas na categoria cibernética podem fazer fallback para o Claude Opus 4.8. Para reexecutar requisições recusadas em outro modelo automaticamente, considere o parâmetro fallbacks com o modo "default" (fallbacks: "default"), que seleciona um modelo de fallback recomendado com base na categoria de recusa em vez de uma lista de modelos mantida manualmente. O fallback do lado do servidor está em beta; o modo "default" requer o cabeçalho beta server-side-fallback-2026-07-01. Consulte Recusas e fallback.
Faça cache de prompts mais curtos: O comprimento mínimo de prompt cacheável no Claude Opus 5 é de 512 tokens, menor do que em modelos Opus anteriores. Prompts que eram curtos demais para cache agora podem criar entradas de cache, sem necessidade de alterações no código. Consulte Cache de prompt para os mínimos por modelo.
Altere ferramentas no meio da conversa (beta): Você pode adicionar ou remover ferramentas entre turnos de uma conversa sem invalidar acertos de cache de prompt em turnos anteriores. Envie o cabeçalho beta mid-conversation-tool-changes-2026-07-01. Isso é útil para cargas de trabalho agênticas que expõem ferramentas progressivamente ou as retiram à medida que uma tarefa avança; sem ele, uma lista de ferramentas alterada invalida o prefixo em cache.
Remova instruções de verificação herdadas e restrinja o escopo: O Claude Opus 5 verifica seu próprio trabalho sem ser instruído a fazê-lo, então remova instruções explícitas de verificação ou autoverificação herdadas de prompts ajustados para modelos anteriores; deixá-las causa verificação excessiva. Para tarefas restritas, limite o escopo da tarefa explicitamente. Consulte Escopo da tarefa e verificação excessiva.

Checklist de migração

Atualize o nome do modelo de claude-opus-4-6 para claude-opus-5 (ou atualize os aliases).
Remova temperature, top_p e top_k dos payloads de requisição.
Substitua thinking: {type: "enabled", budget_tokens: N} por thinking: {type: "adaptive"} mais o parâmetro de esforço, ou remova o campo thinking completamente; o pensamento adaptativo está ativado por padrão no Claude Opus 5.
Revise cargas de trabalho que eram executadas sem um campo thinking: elas são executadas com pensamento no Claude Opus 5. Revise max_tokens, que continua sendo um limite rígido na saída total (pensamento mais texto de resposta), ou passe thinking: {type: "disabled"} com esforço high ou inferior para preservar o comportamento antigo.
Audite requisições que desativam o pensamento: thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400, aplicado em cada requisição. Reative o pensamento ou reduza o esforço para high ou inferior.
Remova quaisquer prefills de mensagens do assistente.
Se a sua UI exibe conteúdo de pensamento, opte explicitamente pela sumarização do pensamento.
Refaça o benchmark de custo e latência de ponta a ponta sob a tokenização atualizada.
Reajuste max_tokens para levar em conta a tokenização atualizada.
Reteste quaisquer estimativas de contagem de tokens do lado do cliente.
Se a sua aplicação envia imagens, reorce o orçamento para suporte a imagens de alta resolução (até aproximadamente 3x mais tokens de imagem por imagem em resolução total). Reduza a resolução antes de enviar se você não precisar da fidelidade adicional.
Se você consome coordenadas de apontamento ou de bounding box do modelo, remova qualquer conversão de fator de escala; as coordenadas são 1:1 com os pixels reais da imagem no Claude Opus 4.7 e modelos posteriores.
Revise os prompts quanto às mudanças de comportamento (comprimento da resposta, literalismo, tom, atualizações de progresso, subagentes, calibração de esforço, acionamento de ferramentas, salvaguardas cibernéticas, tratamento de imagens de alta resolução).
Redefina a linha de base do comprimento da resposta com os prompts existentes de controle de comprimento removidos, depois ajuste explicitamente.
Se estiver usando esforço xhigh ou max, aumente max_tokens para pelo menos 64k como ponto de partida.
Considere adotar orçamentos de tarefa (beta) e alterações de ferramentas no meio da conversa (beta) para fluxos de trabalho agênticos.
Trate stop_reason: "refusal" e considere fallbacks: "default" (beta) para reexecutar requisições recusadas em um modelo de fallback recomendado automaticamente.
Revise prompts próximos ao mínimo de cache: prompts de 512 tokens ou mais agora podem criar entradas de cache no Claude Opus 5.
Se você usa web fetch, planeje uma alternativa: ele não está disponível no Claude Opus 5.
Se a sua organização tem um compromisso de Priority Tier, observe que o Priority Tier não é compatível com o Claude Opus 5.
Remova instruções de verificação e autoverificação herdadas de prompts ajustados para modelos anteriores; elas causam verificação excessiva no Claude Opus 5.
Se o seu produto faz trabalho de segurança legítimo, inscreva-se no Cyber Verification Program para obter acesso a restrições menores sobre conteúdo cibernético.

Migrando do Claude Opus 4.5 ou anterior

Se você está migrando do Claude Opus 4.5, Opus 4.1 ou um modelo anterior diretamente para o Claude Opus 5, aplique todas as mudanças anteriores nesta seção mais as seguintes mudanças cumulativas, que entraram em vigor entre o Opus 4.5 e o Opus 4.7. Se você está migrando do Opus 4.6, as mudanças anteriores nesta seção são tudo o que você precisa.

Atualize o nome do seu modelo

# Migração do Opus
model = "claude-opus-4-5"  # Before
model = "claude-opus-5"  # After

Mudanças incompatíveis

Remoção de prefill é abordada nas mudanças incompatíveis para migração do Claude Opus 4.6.
Aspas em parâmetros de ferramentas: O Claude Opus 4.6 e modelos posteriores podem produzir escape de strings JSON ligeiramente diferente em argumentos de chamadas de ferramentas (por exemplo, tratamento diferente de escapes Unicode ou escape de barra). Se você analisa o input da chamada de ferramenta como uma string bruta em vez de usar um parser JSON, verifique sua lógica de parsing. Parsers JSON padrão (como json.loads() ou JSON.parse()) tratam essas diferenças automaticamente.

Mudanças recomendadas

Essas mudanças melhoram sua experiência no Claude Opus 4.7 e modelos posteriores. Itens marcados como (obrigatório no Opus 4.7) eram recomendações opcionais quando o Opus 4.6 foi lançado, mas agora são obrigatórios; o restante continua recomendado.

Migre para pensamento adaptativo (obrigatório no Opus 4.7): thinking: {type: "enabled", budget_tokens: N} retorna um erro 400 no Claude Opus 4.7 e modelos posteriores. Mude para thinking: {type: "adaptive"} e use o parâmetro de esforço para controlar a profundidade do pensamento; no Claude Opus 5, thinking: {type: "adaptive"} é equivalente a omitir o campo thinking, que é executado com pensamento adaptativo por padrão. Consulte Pensamento.
response = client.beta.messages.create( model="claude-opus-4-5", max_tokens=16000, thinking={"type": "enabled", "budget_tokens": 32000}, betas=["interleaved-thinking-2025-05-14"], messages=[{"role": "user", "content": "Your prompt here"}], )
Observe que a migração também muda de client.beta.messages.create para client.messages.create. Pensamento adaptativo e esforço são recursos GA e não requerem o namespace beta do SDK nem quaisquer cabeçalhos beta.
Remova o cabeçalho beta de esforço: O parâmetro de esforço agora é GA. Remova betas=["effort-2025-11-24"] das suas requisições.
Remova o cabeçalho beta de streaming de ferramentas de granularidade fina: O streaming de ferramentas de granularidade fina agora é GA. Remova betas=["fine-grained-tool-streaming-2025-05-14"] das suas requisições.
Remova o cabeçalho beta de pensamento intercalado: O pensamento adaptativo habilita automaticamente o pensamento intercalado no Claude Opus 4.7, Opus 4.6 e Sonnet 4.6. Remova betas=["interleaved-thinking-2025-05-14"] das suas requisições. O cabeçalho ainda é funcional no Sonnet 4.6 com pensamento estendido manual, mas o modo manual está descontinuado.
Migre para output_config.format: Se estiver usando saídas estruturadas, atualize output_format={...} para output_config={"format": {...}}. O parâmetro antigo continua funcional, mas está descontinuado e será removido em uma versão futura do modelo.

Migrando do Claude 4.1 ou anterior

Se você está migrando do Opus 4.1 ou modelos anteriores diretamente para o Claude Opus 5, aplique todas as mudanças anteriores nesta seção, mais as mudanças adicionais nesta subseção.

# Do Opus 4.1
model = "claude-opus-4-1-20250805"  # Before
model = "claude-opus-5"  # After

# Do Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Before
model = "claude-opus-5"  # After

Mudanças incompatíveis adicionais

Remova parâmetros de amostragem

Esta é uma mudança incompatível ao migrar de modelos Claude 3.x.

A partir do Claude Opus 4.7, definir temperature, top_p ou top_k para qualquer valor não padrão retorna um erro 400. O caminho de migração mais seguro é omitir esses parâmetros completamente das requisições e usar prompts para orientar o comportamento do modelo. Se você estava usando temperature = 0 para determinismo, observe que isso nunca garantiu saídas idênticas.
# Antes - Isso causará erro nos modelos Claude 4+ response = client.messages.create( model="claude-3-7-sonnet-20250219", temperature=0.7, top_p=0.9, # Non-default sampling params return 400 on Opus 4.7 # ... ) # Depois response = client.messages.create( model="claude-opus-5", # ... )
Atualize as versões das ferramentas

Esta é uma mudança incompatível ao migrar de modelos Claude 3.x.

Atualize para as versões mais recentes das ferramentas. Remova qualquer código que use o comando undo_edit.
# Antes tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}] # Depois tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
- Editor de texto: Use text_editor_20250728 e str_replace_based_edit_tool. Consulte a documentação da ferramenta de editor de texto para obter detalhes.
- Execução de código: Faça upgrade para code_execution_20260521. Consulte a documentação da ferramenta de execução de código para obter instruções de migração.

Trate o stop reason refusal

Atualize sua aplicação para tratar stop reasons refusal:

response = client.messages.create(...)

if response.stop_reason == "refusal":
    # Trate a recusa adequadamente
    pass

Trate o stop reason model_context_window_exceeded

Modelos Claude 4.5+ retornam um stop reason model_context_window_exceeded quando a geração para por atingir o limite da janela de contexto, em vez do limite max_tokens solicitado. Atualize sua aplicação para tratar esse novo stop reason:
response = client.messages.create(...) if response.stop_reason == "model_context_window_exceeded": # Trate o limite da janela de contexto adequadamente pass
Verifique o tratamento de parâmetros de ferramentas (quebras de linha finais)

Modelos Claude 4.5+ preservam quebras de linha finais em parâmetros de string de chamadas de ferramentas que anteriormente eram removidas. Se suas ferramentas dependem de correspondência exata de string com parâmetros de chamadas de ferramentas, verifique se sua lógica trata quebras de linha finais corretamente.
Atualize seus prompts para mudanças comportamentais

Modelos Claude 4+ têm um estilo de comunicação mais conciso e direto e requerem direcionamento explícito. Revise as melhores práticas de prompting para orientação de otimização.

Mudanças recomendadas adicionais

Remova cabeçalhos beta legados: Remova token-efficient-tools-2025-02-19 e output-128k-2025-02-19. Todos os modelos Claude 4+ têm uso de ferramentas eficiente em tokens integrado e esses cabeçalhos não têm efeito.

Checklist de migração (do Claude Opus 4.5 ou anterior)

Atualize o ID do modelo para claude-opus-5
Aplique todas as mudanças incompatíveis para migração do Claude Opus 4.6 (pensamento estendido removido, pensamento ativado por padrão, limite de esforço ao desativar o pensamento, parâmetros de amostragem removidos, exibição de pensamento omitida por padrão, tokenização atualizada)
INCOMPATÍVEL: Remova prefills de mensagens do assistente (retorna erro 400); use saídas estruturadas ou output_config.format em vez disso
INCOMPATÍVEL no Opus 4.7: Substitua thinking: {type: "enabled", budget_tokens: N} por thinking: {type: "adaptive"} mais o parâmetro de esforço (retorna 400 no Opus 4.7)
Verifique se o parsing de JSON de chamadas de ferramentas usa um parser JSON padrão
Remova o cabeçalho beta effort-2025-11-24 (esforço agora é GA)
Remova o cabeçalho beta fine-grained-tool-streaming-2025-05-14
Remova o cabeçalho beta interleaved-thinking-2025-05-14 (pensamento adaptativo habilita pensamento intercalado automaticamente)
Migre output_format para output_config.format (se aplicável)
Se estiver migrando do Claude 4.1 ou anterior: remova temperature, top_p e top_k (valores não padrão retornam 400 no Opus 4.7)
Se estiver migrando do Claude 4.1 ou anterior: atualize as versões das ferramentas (text_editor_20250728, code_execution_20260521)
Se estiver migrando do Claude 4.1 ou anterior: trate o stop reason refusal
Se estiver migrando do Claude 4.1 ou anterior: trate o stop reason model_context_window_exceeded
Se estiver migrando do Claude 4.1 ou anterior: verifique o tratamento de parâmetros de string de ferramentas para quebras de linha finais
Se estiver migrando do Claude 4.1 ou anterior: remova cabeçalhos beta legados (token-efficient-tools-2025-02-19, output-128k-2025-02-19)
Revise e atualize prompts seguindo as melhores práticas de prompting
Teste em ambiente de desenvolvimento antes da implantação em produção

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

O Claude Opus 5 e o Claude Sonnet 5 compartilham a mesma superfície de API: ambos executam com adaptive thinking (pensamento adaptativo) ativado por padrão, ambos definem o parâmetro effort como high por padrão na Claude API e no Claude Code, ambos oferecem uma janela de contexto de 1M de tokens por padrão com 128k tokens máximos de saída, e nenhum dos dois oferece suporte ao Priority Tier. O pensamento estendido manual e parâmetros de amostragem com valores não padrão retornam um erro 400 em ambos os modelos, assim como o preenchimento prévio do assistente.

Atualize o nome do seu modelo

model = "claude-sonnet-5"  # Before
model = "claude-opus-5"  # After

O que mudou

Preços: O Claude Opus 5 tem preço de US$ 5 por milhão de tokens de entrada e US$ 25 por milhão de tokens de saída. O Claude Sonnet 5 tem preço de US$ 2/US$ 10 por milhão de tokens de entrada/saída. Consulte Preços do Claude para ver os preços completos.
Desativar o pensamento é limitado ao effort high: No Claude Sonnet 5, thinking: {type: "disabled"} é aceito em qualquer nível de effort. No Claude Opus 5, é aceito apenas em um nível de effort high ou inferior; uma requisição que combina thinking: {type: "disabled"} com effort xhigh ou max retorna um erro 400, aplicado em cada requisição. Audite as requisições que desativam o pensamento antes de migrar.
Mensagens de sistema no meio da conversa: O Claude Opus 5 aceita mensagens role: "system" imediatamente após um turno do usuário no array messages (sujeito às regras de posicionamento); o Claude Sonnet 5 não aceita. Se você mantém caminhos de código que reconstroem todo o histórico de mensagens para atualizar instruções, pode simplificá-los e preservar os acertos de cache de prompt em turnos anteriores.
Web fetch não está disponível: A ferramenta web fetch está disponível no Claude Sonnet 5, mas não no Claude Opus 5.

Checklist de migração

Atualize o nome do modelo de claude-sonnet-5 para claude-opus-5.
Audite as requisições que desativam o pensamento: thinking: {type: "disabled"} com effort xhigh ou max retorna um erro 400 no Claude Opus 5. Reative o pensamento ou reduza o effort para high ou inferior.
Se você usa web fetch, planeje uma alternativa: não está disponível no Claude Opus 5.
Execute novamente a contagem de tokens no Claude Opus 5 em vez de reutilizar contagens medidas no Claude Sonnet 5, e redefina a linha de base de custo e latência em suas próprias cargas de trabalho; o preço por token é diferente.

Migrando para o Claude Sonnet 5

O Claude Sonnet 5 oferece a melhor combinação de velocidade e inteligência na família de modelos Claude. Ele é construído sobre o Claude Sonnet 4.6.

O Claude Sonnet 5 é uma atualização direta do Claude Sonnet 4.6, com preço de US$ 2/US$ 10 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á está rodando no Claude Sonnet 4.6: o pensamento estendido manual (thinking: {type: "enabled", budget_tokens: N}) e parâmetros de amostragem (temperature, top_p, top_k) definidos com valores não padrão não são mais aceitos e retornam um erro 400. Use adaptive thinking com o parâmetro effort em vez disso. O Claude Sonnet 5 oferece suporte ao mesmo conjunto de recursos que o Claude Sonnet 4.6, incluindo a janela de contexto de 1M de tokens, adaptive thinking, 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. 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 do 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 na saída total (pensamento mais texto de resposta), então revise-o para cargas de trabalho que rodavam sem pensamento no Claude Sonnet 4.6.

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 mudança de código é necessária, mas qualquer coisa que você meça ou orce 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 de max_tokens ajustado para o Claude Sonnet 4.6 pode truncar uma saída equivalente. O preço por token é menor (US$ 2/US$ 10 versus US$ 3/US$ 15 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 na proporção direta. Execute novamente a contagem de tokens no Claude Sonnet 5 em vez de reutilizar contagens medidas em modelos anteriores.
128k tokens máximos de saída (inalterado): O Claude Sonnet 5 oferece suporte a 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.
Preenchimento prévio de mensagem do assistente (inalterado): O preenchimento prévio da 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 mudança adicional é necessária. Use saídas estruturadas, instruções no prompt do sistema ou output_config.format em vez disso.
Adaptive thinking 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 adaptive thinking. 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.
O adaptive thinking está ativado por padrão para o Claude Sonnet 5. O campo thinking é mostrado explicitamente aqui para definir display: "summarized"; se você omitir thinking, o Claude Sonnet 5 omite o conteúdo de pensamento da resposta por padrão. Para padrões por modelo, consulte Configurações que cada modelo rejeita.
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}")
Parâmetros de amostragem removidos: Parâmetros de amostragem (temperature, top_p, top_k) definidos com um valor não padrão não são aceitos e retornam um erro 400.
Salvaguardas de cibersegurança: O Claude Sonnet 5 é o primeiro modelo da classe 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. As recusas retornam como uma resposta HTTP 200 bem-sucedida com stop_reason: "refusal", não como um erro. Consulte Salvaguardas, avisos e recursos para contexto.

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 esperado da sua saída e aumente-os até o máximo de 128k (inalterado em relação ao Claude Sonnet 4.6) onde for útil.
Remova a configuração thinking: {type: "enabled", budget_tokens: N} (retorna um erro 400). O adaptive thinking está ativado por padrão; passe {type: "disabled"} para desativá-lo, ou use o parâmetro effort para controlar a profundidade.
Remova os parâmetros temperature, top_p e top_k definidos com valores não 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.
Redefina a linha de base de custo em 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

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

Esta é uma mudança incompatível ao migrar do Sonnet 4.5 ou anterior.

O preenchimento prévio de mensagens do assistente retorna um erro 400 no Claude Sonnet 4.6 e em 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 inadequadas: O Claude agora é muito melhor em recusas apropriadas. 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 contexto em conversas longas): Injete o que antes eram lembretes de preenchimento prévio do assistente no turno do usuário em vez disso.
O escape de JSON em parâmetros de ferramentas pode diferir

Esta é uma mudança incompatível ao migrar do Sonnet 4.5 ou anterior.

O escape de strings JSON em parâmetros de ferramentas pode diferir de 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 adaptive thinking está ativado por padrão, então a maioria das cargas de trabalho não precisa de nenhuma configuração de 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

Remova os parâmetros de amostragem

Esta é uma mudança incompatível ao migrar de modelos Claude 3.x.

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

Esta é uma mudança incompatível ao migrar de modelos Claude 3.x.

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.
Trate o stop reason refusal

Atualize sua aplicação para tratar stop reasons refusal.
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 adaptive thinking 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

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 adaptive thinking 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.
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 não padrão retorna um erro 400. Remova esses parâmetros e use prompting para orientar o comportamento do modelo.
Preenchimento prévio do assistente removido: O preenchimento prévio da 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.
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, então execute novamente a contagem de tokens em vez de reutilizar contagens medidas no Claude Haiku 4.5.
Preços: O Claude Haiku 4.5 tem preço de US$ 1/US$ 5 por milhão de tokens de entrada/saída. O Claude Sonnet 5 tem preço de US$ 2/US$ 10 por milhão de tokens de entrada/saída. Consulte Preços do Claude.
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, avisos e recursos para contexto.

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 adaptive thinking 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.
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, então nenhuma configuração existente é transferida.
Remova as configurações de temperature e top_p (valores não 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.
Redefina a linha de base de custo em sua carga de trabalho típica antes da implantação em produção; o preço por token é diferente.

Migrando para o Claude Haiku 4.5

O Claude Haiku 4.5 é o modelo Haiku mais rápido e inteligente, com desempenho próximo ao de fronteira, oferecendo qualidade de modelo premium para aplicações interativas e processamento de alto volume.

Para uma visão geral completa das capacidades, consulte a visão geral dos modelos.

Migrando para o Claude Haiku 4.5 a partir do Claude Haiku 3.5 e modelos Haiku anteriores

Atualize o nome do seu modelo:

# Do Haiku 3.5
model = "claude-3-5-haiku-20241022"  # Before
model = "claude-haiku-4-5-20251001"  # After

Revise os novos limites de taxa: O Haiku 4.5 tem limites de taxa separados do Haiku 3.5. Consulte a documentação de Limites de taxa para detalhes.

Explore novas capacidades: Consulte a visão geral dos modelos para detalhes sobre consciência de contexto, capacidade de saída aumentada (64k tokens), maior inteligência e velocidade aprimorada.

Mudanças incompatíveis

Estas mudanças incompatíveis se aplicam ao migrar de modelos Claude 3.x Haiku.

Atualize os parâmetros de amostragem

Esta é uma mudança incompatível ao migrar de modelos Claude 3.x.

Use apenas temperature OU top_p, não ambos. Definir ambos retorna um erro 400 no Claude Haiku 4.5.
Atualize as versões das ferramentas

Esta é uma mudança incompatível ao migrar de modelos Claude 3.x.

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

Atualize sua aplicação para tratar stop reasons refusal.
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.

Checklist de migração do Haiku 4.5

Atualize o ID do modelo para claude-haiku-4-5-20251001
INCOMPATÍVEL: Atualize as versões das ferramentas para as mais recentes (text_editor_20250728, code_execution_20250825); versões legadas não são suportadas
INCOMPATÍVEL: Remova qualquer código que use o comando undo_edit (se aplicável)
INCOMPATÍVEL: Atualize os parâmetros de amostragem para usar apenas temperature OU top_p, não ambos (definir ambos retorna um erro 400)
Trate o novo stop reason refusal em sua aplicação
Revise e ajuste para os novos limites de taxa (separados do Haiku 3.5)
Revise e atualize os prompts seguindo as melhores práticas de prompting
Considere habilitar o pensamento estendido para tarefas complexas de raciocínio
Teste em ambiente de desenvolvimento antes da implantação em produção

Obtenha ajuda

Consulte a documentação da API para especificações detalhadas
Revise as capacidades dos modelos para comparações de desempenho
Revise as notas de lançamento da API para atualizações da API
Entre em contato com o suporte se encontrar problemas durante a migração

Was this page helpful?

Migrando para Claude Mythos 5 e Claude Fable 5

Migrando para Claude Mythos 5 e Claude Fable 5 a partir do Claude Mythos Preview

Atualize o nome do seu modelo

Recursos não disponíveis no Claude Mythos 5 e Claude Fable 5

Contagem de tokens e cobrança

Lista de verificação de migração

Migrando para Claude Mythos 5 e Claude Fable 5 a partir do Claude Opus 5

Atualize o nome do seu modelo

O que mudou

Lista de verificação de migração

Migrando para Claude Mythos 5 e Claude Fable 5 a partir do Claude Opus 4.8

Atualize o nome do seu modelo

O que mudou

Lista de verificação de migração

Migrando para Claude Opus 5

Migrando para Claude Opus 5 a partir do Claude Opus 4.8

Atualize o nome do seu modelo

Alterações incompatíveis

Alterações recomendadas

Lista de verificação de migração

Migrando para o Claude Opus 5 a partir do Claude Opus 4.7

Atualize o nome do seu modelo

Mudanças incompatíveis

O que mudou

Mudanças recomendadas

Checklist de migração

Migrando para o Claude Opus 5 a partir do Claude Opus 4.6 e modelos Opus anteriores

Atualize o nome do seu modelo

Mudanças incompatíveis

Escolhendo um nível de esforço

Mudanças de comportamento

Mudanças recomendadas

Checklist de migração

Migrando do Claude Opus 4.5 ou anterior

Atualize o nome do seu modelo

Mudanças incompatíveis

Mudanças recomendadas

Migrando do Claude 4.1 ou anterior

Mudanças incompatíveis adicionais

Mudanças recomendadas adicionais

Checklist de migração (do Claude Opus 4.5 ou anterior)

Migrando para o Claude Opus 5 a partir do Claude Sonnet 5

Atualize o nome do seu modelo

O que mudou

Checklist de migração

Migrando para o Claude Sonnet 5

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

Atualize o nome do seu modelo

O que mudou

Checklist de migração

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

Mudanças incompatíveis

Ao migrar do Sonnet 4.5

Ao migrar do Claude 3.x

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

Atualize o nome do seu modelo

O que mudou

Checklist de migração

Migrando para o Claude Haiku 4.5

Migrando para o Claude Haiku 4.5 a partir do Claude Haiku 3.5 e modelos Haiku anteriores

Mudanças incompatíveis

Checklist de migração do Haiku 4.5

Obtenha ajuda

Migrando para Claude Mythos 5 e Claude Fable 5

Migrando para Claude Mythos 5 e Claude Fable 5 a partir do Claude Mythos Preview

Atualize o nome do seu modelo

Recursos não disponíveis no Claude Mythos 5 e Claude Fable 5

Contagem de tokens e cobrança

Lista de verificação de migração

Migrando para Claude Mythos 5 e Claude Fable 5 a partir do Claude Opus 5

Atualize o nome do seu modelo

O que mudou

Lista de verificação de migração

Migrando para Claude Mythos 5 e Claude Fable 5 a partir do Claude Opus 4.8

Atualize o nome do seu modelo

O que mudou

Lista de verificação de migração

Migrando para Claude Opus 5

Migrando para Claude Opus 5 a partir do Claude Opus 4.8

Atualize o nome do seu modelo

Alterações incompatíveis

Alterações recomendadas

Lista de verificação de migração

Migrando para o Claude Opus 5 a partir do Claude Opus 4.7

Atualize o nome do seu modelo

Mudanças incompatíveis

O que mudou

Mudanças recomendadas

Checklist de migração

Migrando para o Claude Opus 5 a partir do Claude Opus 4.6 e modelos Opus anteriores

Atualize o nome do seu modelo

Mudanças incompatíveis

Escolhendo um nível de esforço

Mudanças de comportamento

Mudanças recomendadas

Checklist de migração

Migrando do Claude Opus 4.5 ou anterior

Migrando do Claude 4.1 ou anterior

Checklist de migração (do Claude Opus 4.5 ou anterior)

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

Atualize o nome do seu modelo

O que mudou

Checklist de migração

Migrando para o Claude Sonnet 5

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

Atualize o nome do seu modelo

O que mudou

Checklist de migração

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

Mudanças incompatíveis

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

Atualize o nome do seu modelo

O que mudou

Checklist de migração

Migrando para o Claude Haiku 4.5

Migrando para o Claude Haiku 4.5 a partir do Claude Haiku 3.5 e modelos Haiku anteriores

Mudanças incompatíveis

Checklist de migração do Haiku 4.5

Obtenha ajuda