Migrando do Claude Opus 4.8 para o Opus 5: Todas as Alterações Impactantes

Trocar claude-opus-4-8 por claude-opus-5 parece ser uma mudança de uma única linha. Em grande parte, é. Mas alguns padrões mudaram discretamente, uma combinação de requisição anteriormente válida agora retorna um erro 400 categórico, e um recurso pelo qual equipes empresariais pagam está ausente no novo modelo.

A Anthropic lançou o Claude Opus 5 em 24 de julho de 2026, com o mesmo preço do Opus 4.8 (US$ 5 por milhão de tokens de entrada, US$ 25 por milhão de tokens de saída), então raramente esta é uma decisão orçamentária. É uma decisão de correção. Abaixo está cada diferença que pode quebrar uma integração funcionando, ordenada pela probabilidade de te afetar no primeiro dia, com trechos de antes e depois que você pode colar em seu cliente. O próprio guia de migração do Opus 4.8 para Opus 5 da Anthropic é a principal fonte para a superfície da API. Para testar cada mudança contra o endpoint ao vivo primeiro, salve uma requisição no Apidog e clone-a por variante.

A versão curta

1. `thinking` está ativado por padrão, e max_tokens ainda limita tudo

Esta é a mudança que quebra um código silencioso e funcional.

No Opus 4.8, uma requisição sem o campo thinking era executada sem "pensar". No Opus 5, essa mesma requisição executa "pensamento" adaptativo. Seu JSON não mudou, mas o modelo agora gasta tokens raciocinando antes de escrever a resposta visível. E max_tokens permanece um limite rígido para os tokens de "pensamento" mais os tokens de resposta juntos, então uma requisição que se encaixava confortavelmente em um orçamento de 1.024 tokens no 4.8 agora pode consumir a maior parte desse orçamento em "pensamento" e retornar uma resposta truncada.

Aqui está o formato de uma requisição que costumava ser segura:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Resuma este relatório de incidente em três pontos."}
  ]
}

Mude o ID do modelo e nada mais, e você terá um risco de truncamento. A solução é dar margem ao orçamento:

{
  "model": "claude-opus-5",
  "max_tokens": 8192,
  "messages": [
    {"role": "user", "content": "Resuma este relatório de incidente em três pontos."}
  ]
}

Duas coisas para verificar depois de aumentar o limite. Observe stop_reason na resposta: max_tokens significa que você foi cortado, end_turn significa que o modelo terminou. Em seguida, leia o bloco usage para ver quanto do orçamento o "pensamento" realmente consumiu em seus prompts reais, e dimensione o número a partir da medição, e não de um palpite.

Se você realmente deseja o comportamento antigo sem "pensamento", envie thinking: {"type": "disabled"} explicitamente. Leia a próxima seção primeiro, porque esse campo agora interage com o `effort` de uma forma que retorna um erro.

2. O erro 400: `thinking` desabilitado mais `xhigh` ou `max` effort

Esta é a armadilha mais provável de aparecer em seus logs de erro, porque ambas as partes eram válidas separadamente no Opus 4.8.

No Opus 5, thinking: {"type": "disabled"} combinado com output_config.effort definido como xhigh ou max retorna um HTTP 400. A Anthropic o impõe por requisição, então ele falha imediata e consistentemente em vez de degradar. A lógica é direta: os dois níveis de `effort` mais altos existem para "comprar" mais "pensamento", então pedir o `effort` máximo com o "pensamento" desativado é uma contradição.

A requisição que agora falha:

{
  "model": "claude-opus-5",
  "max_tokens": 8192,
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "xhigh"},
  "messages": [
    {"role": "user", "content": "Refatore este módulo e explique as compensações."}
  ]
}

Correção A, mantenha a capacidade. Descarte o campo thinking, mantenha o `effort` alto. Esta é a direção recomendada pela Anthropic, e é a que deve ser escolhida para codificação e trabalho agêntico:

{
  "model": "claude-opus-5",
  "max_tokens": 32000,
  "output_config": {"effort": "xhigh"},
  "messages": [
    {"role": "user", "content": "Refatore este módulo e explique as compensações."}
  ]
}

Correção B, mantenha o `thinking` desativado. Para um caminho sensível à latência que realmente não precisa de "pensamento", mantenha disabled e reduza o `effort` para high ou inferior:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "high"},
  "messages": [
    {"role": "user", "content": "Classifique este ticket em uma das cinco categorias."}
  ]
}

Uma ressalva sobre a Correção B. A Anthropic documenta dois artefatos que aparecem ocasionalmente com o "pensamento" desabilitado: chamadas de ferramentas escritas como texto simples em vez de serem executadas, e tags XML internas como <thinking> vazando para a saída visível. Em um loop agêntico, o texto vazado também contamina as próximas interações. A mitigação da própria Anthropic é manter o "pensamento" ativado e controlar o custo com um nível de `effort` mais baixo. Trate a Correção B como a opção restrita, não a padrão.

3. Os níveis de `effort` foram recalibrados, então refaça a varredura em vez de copiar as configurações

O Opus 5 usa `high` `effort` por padrão, e os próprios níveis foram recalibrados. low e medium são significativamente mais fortes no Opus 5 do que nos modelos Opus anteriores, então uma configuração que você ajustou no 4.8 não resulta mais no mesmo ponto de custo e qualidade. A Anthropic afirma claramente para executar uma nova varredura de `effort` em vez de transferir sua configuração do 4.8, e esse conselho funciona nos dois sentidos:

• Cargas de trabalho fixadas em high ou xhigh no 4.8 para qualidade podem se manter em medium no Opus 5, o que é uma redução real na conta com preços idênticos por token.
• Cargas de trabalho fixadas em low para custo podem valer a pena subir um nível, porque a qualidade por token melhorou.

Para codificação e trabalho agêntico de longo prazo, xhigh continua sendo o ponto de partida recomendado. Combine-o com um max_tokens generoso (64k é um orçamento inicial sensato nos níveis superiores) para que o "pensamento" tenha para onde ir.

Execute a varredura em seu próprio conjunto de avaliação, não em um benchmark. Fixe o prompt, varie apenas o valor de `effort` e registre a qualidade da saída, a latência e o usage para cada nível. O mergulho profundo no parâmetro `effort` do Claude Opus 5 aborda a mecânica de cada nível; para o lado do custo da mesma decisão, consulte a análise de preços do Opus 5.

4. Remova o cabeçalho beta de contexto longo

O Opus 5 vem com uma janela de contexto de 1M de tokens como padrão e máximo. Não há cabeçalho beta para ativá-lo e nenhum prêmio de preço de contexto longo associado.

Se o seu cliente ainda envia o valor beta de contexto estendido no cabeçalho anthropic-beta da sua configuração do Opus 4.8, ele agora é peso morto. Remova-o. Valores beta desatualizados em um cliente HTTP compartilhado são como você acaba depurando uma requisição não relacionada seis meses depois.

A saída máxima na API Messages é de 128k tokens. Se precisar de mais, a API Batch vai até 300k tokens de saída com o cabeçalho beta output-300k-2026-03-24, um opt-in separado de qualquer coisa que você estivesse fazendo para o comprimento do contexto.

5. O mínimo de cache de prompt cai para 512 tokens

No Opus 4.8, um segmento de prompt tinha que atingir 1.024 tokens para ser elegível para cache. No Opus 5, o limite é de 512. Nada no seu código precisa mudar, e leituras de cache a US$ 0,50 por milhão são os tokens mais baratos na tabela de preços contra US$ 5 de entrada base.

O que vale a pena fazer é uma revisão. Procure prompts de sistema, definições de ferramentas e blocos few-shot que estavam entre 512 e 1.024 tokens e nunca valeram um ponto de interrupção cache_control antes. Agora valem. Confirme o efeito lendo cache_read_input_tokens no bloco usage da resposta: na segunda chamada idêntica, ele deve ser diferente de zero. Nosso guia para reduzir a conta da API Claude aborda a estratégia de cache mais ampla.

6. Mensagens de sistema no meio da conversa agora são aceitas

O Opus 4.8 rejeitava uma entrada {"role": "system"} dentro do array messages com um 400. O Opus 5 a aceita. Isso é aditivo, então não quebra nada, mas pode eliminar uma solução alternativa. Se você construiu um mecanismo que integra mudanças de instrução no meio da conversa em uma "turn" de usuário sintética, agora pode colocar a instrução em linha onde ela pertence:

{
  "model": "claude-opus-5",
  "max_tokens": 8192,
  "messages": [
    {"role": "user", "content": "Elabore a nota de lançamento."},
    {"role": "assistant", "content": "Aqui está um primeiro rascunho..."},
    {"role": "system", "content": "A partir de agora, mantenha as respostas abaixo de 150 palavras."},
    {"role": "user", "content": "Aperte o texto."}
  ]
}

Esta é uma capacidade por modelo. Se você encaminhar o mesmo histórico de conversa para o Opus 4.8 como fallback, o modelo mais antigo ainda retornará um 400 nessa mensagem.

7. O Nível de Prioridade não é suportado no Opus 5

Este atinge as equipes empresariais, e é fácil de passar despercebido porque é uma ausência, e não um erro que você possa buscar. O Opus 4.8 suporta o Nível de Prioridade. O Opus 5 não. Se você comprou throughput garantido para assegurar a latência em um caminho de produção, a migração desse caminho o move de volta para a capacidade padrão.

Não há solução inteligente. Ou você mantém o tráfego crítico de latência no claude-opus-4-8 enquanto todo o resto migra para o Opus 5, ou aceita a capacidade padrão e mede se sua latência de cauda realmente se degrada. Divida a migração por carga de trabalho em vez de mudar toda a frota de uma vez.

8. O Modo Rápido agora funciona, e há um novo fallback para recusas cibernéticas

O Modo Rápido funciona no Opus 5. Ele retornava um erro no Opus 4.7 e funcionava silenciosamente na velocidade padrão no Opus 4.6. No Opus 5, ele oferece aproximadamente 2,5x a velocidade de saída a US$ 10 por milhão de entrada e US$ 50 por milhão de saída. É uma prévia de pesquisa, apenas para API de primeira parte (não Amazon Bedrock, Google Cloud ou Microsoft Foundry), e não se combina com a API Batch. Use-o em caminhos interativos, não em trabalhos em segundo plano.

Fallback do lado do servidor para recusas cibernéticas. Enviar fallbacks: "default" com o cabeçalho beta server-side-fallback-2026-07-01 faz com que uma requisição que o Opus 5 recusa por motivos de categoria cibernética retorne automaticamente ao Opus 4.8. Ferramentas de segurança são onde isso se destaca.

Há também um cabeçalho beta mid-conversation-tool-changes-2026-07-01 que permite adicionar ou remover definições de ferramentas entre turnos sem invalidar o cache de prompt: uma alavanca de custo para sessões de agente longas com um conjunto de ferramentas em mudança.

9. O que não mudou

Economiza tempo saber o que você pode deixar como está:

• Parâmetros de amostragem ainda retornam um 400. temperature, top_p e top_k com valores não padrão são rejeitados, assim como no Opus 4.8. Direcione o comportamento através do prompt do sistema.
• As contagens de tokens são aproximadamente as mesmas. O Opus 5 usa a mesma família de tokenizadores que o 4.8, então os orçamentos de tokens e modelos de custo existentes são mantidos sem uma nova contagem. Isso é o oposto da mudança do Sonnet 4.6 para o Sonnet 5, que alterou as contagens em cerca de 30%.
• O preço base é idêntico. US$ 5 de entrada, US$ 25 de saída, igualando o Opus 4.8, 4.7, 4.6 e 4.5. Consulte a página de preços do Opus 4.8.
• Formato de requisição e resposta. Streaming, uso de ferramentas, visão, saídas estruturadas e batch funcionam da mesma forma que antes.

Uma coisa mudou mesmo onde a API não mudou: o Opus 5 verifica seu próprio trabalho sem ser solicitado, então as instruções de "verifique sua resposta" herdadas causam super-verificação e desperdiçam tokens. As respostas padrão também são mais longas do que as do 4.8, e a diminuição do `effort` corta o "pensamento" em vez do comprimento visível, então peça concisão explicitamente. Essas são correções no nível do prompt, abordadas em como criar prompts para Claude Opus 5.

Verifique a migração antes de implementá-la

Cada item acima é uma diferença de nível HTTP, o que o torna testável fora da sua aplicação. Um loop funcional no Apidog:

1. Salve uma requisição para o endpoint Messages com sua chave armazenada como uma variável de ambiente, nunca embutida no corpo.
2. Clone-a em variantes: linha de base claude-opus-4-8, claude-opus-5 com padrões, e um clone por nível de `effort`.
3. Dispare intencionalmente a combinação de `thinking` desabilitado mais xhigh e registre o corpo do 400, para que você o reconheça nos logs de produção.
4. Afirme em stop_reason para que uma resposta truncada de max_tokens faça seu teste falhar em vez de enviar uma resposta sutilmente pior.
5. Envie uma requisição armazenada em cache idêntica duas vezes e verifique usage.cache_read_input_tokens na segunda chamada.
6. Execute uma requisição de streaming e confirme que seu parser SSE lida com os blocos de `thinking` que agora chegam por padrão.

Baixe o Apidog para manter isso como uma coleção reutilizável para cada futura troca de modelo.

Uma ressalva honesta antes de você migrar tudo

O Opus 5 não é o topo da pilha Claude. O Fable 5 continua sendo o modelo mais capaz da Anthropic amplamente lançado, e o Opus 5 ainda fica atrás do Mythos 5 em exploração de segurança cibernética e pesquisa biológica autônoma. A própria Anthropic diz isso na postagem de lançamento. As alegações de benchmark de lançamento (Frontier-Bench, ARC-AGI 3, OSWorld 2.0, CursorBench 3.2) são executadas pelo fornecedor e não reproduzidas independentemente em 25 de julho de 2026. Trate-as como números relatados pela Anthropic e execute suas próprias avaliações antes de comprometer uma carga de trabalho de produção. O resumo preciso: capacidade de classe "fronteira" pela metade do preço "fronteira", com um limite nomeado acima dela.

Lista de verificação da migração

Siga esta ordem:

1. Mude a string do modelo para exatamente claude-opus-5. Sem sufixo de data.
2. Aumente max_tokens em todas as requisições que anteriormente omitiam thinking. O `thinking` agora é executado por padrão e compartilha esse orçamento.
3. Procure em sua base de código por "disabled" e confirme que nenhuma requisição o associa a `effort` xhigh ou max. Essa combinação resulta em um 400 categórico.
4. Remova o valor beta de contexto longo de anthropic-beta. A janela de 1M agora é o padrão.
5. Reexecute sua varredura de `effort` do zero em suas próprias avaliações. Não transfira as configurações do 4.8.
6. Adicione pontos de interrupção cache_control a segmentos de prompt entre 512 e 1.024 tokens.
7. Identifique qualquer tráfego no Nível de Prioridade e decida por carga de trabalho se ele permanece em claude-opus-4-8.
8. Exclua as instruções de verificação herdadas de seus prompts e adicione instruções explícitas de concisão onde o comprimento da saída for importante.
9. Opcionalmente, habilite fallbacks: "default" se sua carga de trabalho acionar recusas de categoria cibernética.
10. Afirme em stop_reason em seu conjunto de testes para que o truncamento apareça como uma falha, e não como uma resposta sutilmente pior.

Para um passo a passo completo da requisição, consulte o guia da API Claude Opus 5, ou comece com o que é Claude Opus 5 para especificações e disponibilidade. Se você ainda usa o modelo antigo em alguns lugares, o explicador do Opus 4.8 e seu passo a passo da API permanecem precisos para ele. A visão geral dos modelos da Anthropic é a fonte oficial para IDs, janelas de contexto e datas de corte.

FAQ

A migração do Opus 4.8 para o Opus 5 é uma migração direta? Quase, mas não totalmente. Mudar a string do modelo funciona para a maioria das requisições. Duas coisas podem quebrar: o `thinking` agora é executado por padrão e compartilha seu orçamento de max_tokens, e thinking: {"type": "disabled"} com `effort` xhigh ou max retorna um 400. O tráfego do Nível de Prioridade também precisa de uma decisão, já que o Opus 5 não o suporta.

Por que estou recebendo um 400 depois de mudar para claude-opus-5? A causa mais comum é desabilitar o `thinking` ao solicitar `effort` xhigh ou max. Ou remova o campo thinking e mantenha o `effort` alto, ou mantenha o `thinking` desabilitado e diminua o `effort` para high ou menos. Valores não padrão para temperature, top_p ou top_k também ainda retornam um 400, exatamente como no Opus 4.8.

Preciso recontar meus tokens depois de migrar? Não. O Opus 5 usa a mesma família de tokenizadores que o Opus 4.8, então as contagens permanecem aproximadamente as mesmas e os orçamentos existentes são mantidos. A sobrecarga do prompt de sistema para uso de ferramentas é ligeiramente menor, com 286 tokens versus 290. O preço base também é idêntico, a US$ 5 de entrada e US$ 25 de saída, embora sua conta ainda possa mudar se o `thinking` por padrão aumentar os tokens de saída.