Claude Platform Docs
Modelos e preçosClaude Haiku 5.5

Guia de migração para o Claude Haiku 5.5

Migre para o Claude Haiku 5.5 a partir de modelos Haiku anteriores com este guia de migração. As orientações para habilitar o Claude Haiku 5.5 incluem o novo ID do modelo, configurações que retornam erros, mudanças no pensamento e uma checklist para cada modelo de partida.

Claude Code

Deixe o Claude Code migrar seu código para você

/claude-api migrate este projeto para claude-haiku-5-5

Este guia aborda a migração de código que chama o Claude Haiku 4.5 para o Claude Haiku 5.5. Para código que chama o Claude Haiku 3.5 ou o Claude Haiku 3, faça também as alterações em Migrando para o Claude Haiku 5.5 a partir do Claude Haiku 3.5 e de modelos Haiku anteriores. Para subir para um modelo Sonnet ou Opus em vez disso, consulte Guias de migração. Para saber por quanto tempo o Claude Haiku 4.5 permanece disponível, consulte Descontinuações de modelos.

Checklist de migração por modelo de partida

Percorra os grupos de cima para baixo e pare depois daquele que menciona seu modelo atual. Se você usa o Claude Haiku 4.5, o primeiro grupo é a lista completa. Cada item é uma alteração a ser feita no seu código.

Todos os modelos de partida

  1. Substitua o ID do modelo pelo ID do Claude Haiku 5.5 para sua plataforma. Consulte Usar o ID do modelo Claude Haiku 5.5.
  2. Reconte seus prompts e revise os limites de max_tokens e as estimativas de custo, porque o mesmo texto conta como mais tokens e imagens grandes contam como mais tokens visuais. Consulte Recontar tokens.
  3. Se suas requisições enviam thinking: {"type": "enabled", "budget_tokens": N}, altere thinking para {"type": "adaptive"}. Consulte Configurar o pensamento.
  4. Se seu código lê o primeiro bloco de conteúdo como a resposta, selecione os blocos por type em vez disso. Consulte Configurar o pensamento.
  5. Remova temperature, top_p e top_k de suas requisições. Consulte Remover parâmetros de amostragem.
  6. Se suas requisições terminam messages com um turno do assistente para o modelo continuar, termine-as com um turno do usuário em vez disso. Consulte Substituir o preenchimento prévio do assistente.
  7. Se você usa computer use (uso do computador), substitua computer_20250124 pelo conjunto de ferramentas computer_toolset_20260801. No Amazon Bedrock, computer_20251124 também funciona. Consulte Mover o uso do computador para o conjunto de ferramentas.
  8. Se você reproduz conversas armazenadas por meio de uma conta diferente, reproduza cada uma por meio da conta que a produziu. Consulte Reproduzir blocos de pensamento por meio da conta que os produziu.
  9. Se seu código altera system, tools ou messages anteriores entre requisições em uma conversa e envia blocos de pensamento de volta, mantenha a conversa somente com acréscimos (append-only). Consulte Manter os turnos anteriores inalterados.
  10. Trate stop_reason: "refusal". O Claude Haiku 5.5 executa classificadores de segurança que podem recusar uma requisição, e ele não tem fallback no lado do servidor. Consulte Recusas de salvaguarda.
  11. Se seus prompts pedem que o modelo escreva seu raciocínio na resposta, como em tags <thinking> ou <reasoning>, remova essas instruções. O Claude Haiku 5.5 pode recusar uma requisição que as inclua e retornar a categoria reasoning_extraction. Consulte Recusas de salvaguarda.

Se sua organização tem um compromisso de Priority Tier no Claude Haiku 4.5, planeje a capacidade separadamente: o Priority Tier não é compatível com o Claude Haiku 5.5.

Claude Haiku 3.5 ou anterior

  1. Substitua o ID do modelo Claude Haiku 3.5 ou Claude Haiku 3 pelo ID do Claude Haiku 5.5 para sua plataforma. Consulte Migrando para o Claude Haiku 5.5 a partir do Claude Haiku 3.5 e de modelos Haiku anteriores.
  2. Se você usa a ferramenta code_execution_20250522, migre para code_execution_20250825 ou posterior.
  3. Se você usa a ferramenta de edição de texto, migre para text_editor_20250728.
  4. Trate os motivos de parada refusal e model_context_window_exceeded.
  5. Se seu código compara exatamente os parâmetros de string das chamadas de ferramentas, leve em conta quebras de linha finais.
  6. Revise seus prompts.

Usar o ID do modelo Claude Haiku 5.5

Substitua o ID do modelo Claude Haiku 4.5 pelo ID do Claude Haiku 5.5 para sua plataforma.

PlataformaClaude Haiku 4.5Claude Haiku 5.5
Claude APIclaude-haiku-4-5-20251001 ou claude-haiku-4-5claude-haiku-5-5
Amazon Bedrockanthropic.claude-haiku-4-5anthropic.claude-haiku-5-5
Claude Platform on AWSclaude-haiku-4-5claude-haiku-5-5
Claude Models on Google Cloud (Anthropic managed)claude-haiku-4-5-20251001claude-haiku-5-5
Claude Models on Google Cloud (Google managed)claude-haiku-4-5@20251001claude-haiku-5-5
Microsoft Foundryclaude-haiku-4-5claude-haiku-5-5

claude-haiku-5-5 é um ID de modelo fixo, sem sufixo de data e sem alias separado.

Recontar tokens

O Claude Haiku 5.5 usa o mesmo “tokenizer” (tokenizador) que o Claude 4.7 e modelos posteriores. Como em todos os modelos que usam esse tokenizador, o mesmo texto de entrada produz aproximadamente 30 por cento mais tokens no Claude Haiku 5.5 do que no Claude Haiku 4.5. O aumento exato depende do conteúdo. Requisições, respostas e eventos de streaming mantêm o mesmo formato. O que muda é tudo o que você mede ou orça em tokens:

  • Os campos usage e os resultados de contagem de tokens são maiores para o mesmo texto.
  • Um determinado número de tokens comporta menos texto.
  • Um limite de max_tokens ajustado para o Claude Haiku 4.5 pode cortar uma saída equivalente.
  • Estimativas de custo feitas a partir das contagens de tokens do Claude Haiku 4.5 precisam ser recalculadas com as contagens e os preços do Claude Haiku 5.5, incluindo seus preços mais altos para prompts longos. Consulte Preços e Preços de contexto longo.

Imagens grandes também podem custar mais tokens. O Claude Haiku 5.5 usa o nível de imagem de alta resolução, que reduz imagens acima de 2.576 pixels no lado maior ou 4.784 tokens visuais. O Claude Haiku 4.5 e modelos Haiku anteriores usam o nível padrão, que reduz imagens acima de 1.568 pixels no lado maior ou 1.568 tokens visuais. Uma imagem de 2.000 por 1.500 pixels custa cerca de 2,5 vezes mais tokens visuais no Claude Haiku 5.5 do que no Claude Haiku 4.5. Consulte Resolução e custo em tokens.

Conte seus prompts com model definido como claude-haiku-5-5 em vez de reutilizar contagens medidas no Claude Haiku 4.5.

Configurar o pensamento

O Claude Haiku 5.5 configura o pensamento de forma diferente do Claude Haiku 4.5. Um valor de thinking igual a {"type": "enabled", "budget_tokens": N} retorna um erro 400, então uma requisição que o envia precisa de um novo valor de thinking.

Antes, uma requisição ao Claude Haiku 4.5 definia thinking como enabled com um orçamento de tokens:

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

Depois, a mesma requisição ao Claude Haiku 5.5 usa “adaptive thinking” (pensamento adaptativo). O valor de thinking muda, e output_config.effort define o quanto o modelo pensa:

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

O pensamento adaptativo vem ativado por padrão, então uma resposta pode começar com um ou mais blocos thinking mesmo quando a requisição não define thinking. Deixe thinking sem definir ou defina-o como {"type": "adaptive"}, e use o esforço como controle: onde o Claude Haiku 4.5 rodava sem pensamento, ou com um orçamento pequeno para economizar tokens, escolha um nível de esforço mais baixo. Em um nível mais baixo, o modelo pensa menos e pode pular o pensamento completamente em requisições mais simples. Para orientações de prompting, consulte Usar o esforço para controlar o pensamento. Selecione os blocos de conteúdo pelo campo type em vez de pela posição, e envie os blocos thinking de volta sem modificações junto com os resultados das ferramentas.

Os tokens de pensamento contam para max_tokens, então uma requisição com um max_tokens pequeno pode parar com stop_reason: "max_tokens" após um bloco thinking e antes de qualquer texto. Se você definiu um max_tokens pequeno para o Claude Haiku 4.5, aumente-o para deixar espaço para o pensamento, ou escolha um nível de esforço mais baixo.

Os blocos de pensamento de turnos anteriores do assistente permanecem no contexto e contam como tokens de entrada, enquanto o Claude Haiku 4.5 mantém apenas os do turno mais recente. Por isso, conversas de vários turnos carregam mais tokens de entrada do que a mudança de tokenizador sozinha explica. Para remover blocos mais antigos, use a limpeza de blocos de pensamento. Consulte Preservação de blocos de pensamento por modelo.

Por padrão, o Claude Haiku 5.5 retorna cada bloco thinking com um campo thinking vazio e apenas uma signature, enquanto o Claude Haiku 4.5 retorna o pensamento resumido. Para receber o pensamento resumido, defina thinking: {"type": "adaptive", "display": "summarized"}.

O Claude Haiku 5.5 aceita um tool_choice forçado (any ou uma ferramenta nomeada), mas a resposta começa com a chamada da ferramenta e não tem bloco thinking. Para permitir que o modelo pense antes de chamar uma ferramenta, use tool_choice: {"type": "auto"} e diga no prompt quando usar a ferramenta.

Uma conversa que você muda do Claude Haiku 4.5 para o Claude Haiku 5.5 mantém seu raciocínio. Para outras trocas, depende dos dois modelos:

TrocaMantém seu raciocínio
Para o Claude Haiku 5.5, a partir do Claude Haiku 4.5 ou anterior, do Claude Sonnet 5 ou anterior, ou do Claude Opus 4.8 ou anteriorSim
Para o Claude Haiku 5.5, a partir de qualquer outro modeloNão. A API descarta os blocos de pensamento desse modelo sem erro.
Do Claude Haiku 5.5 para o Claude Opus 5.5, o Claude Sonnet 5.5, o Claude Fable 5.2 ou o Claude Mythos 5.2Sim, somente na Claude API e no Claude Models on Google Cloud (Google managed)
Do Claude Haiku 5.5 para qualquer outro modeloNão

Consulte Trocar de modelo e voltar. Para trocas que não envolvem o Claude Haiku 5.5, consulte Quais trocas de modelo mantêm o raciocínio na Claude API.

Remover parâmetros de amostragem

No Claude Haiku 5.5, omita temperature, top_p e top_k e use prompts para orientar o comportamento do modelo em vez disso.

Substituir o preenchimento prévio do assistente

Um “prefill” (preenchimento prévio) é um turno final do assistente em messages que o modelo continua. O Claude Haiku 4.5 aceita um quando o pensamento está desativado. O Claude Haiku 5.5 o rejeita com um erro 400, mesmo com o pensamento desativado. Termine messages com um turno do usuário e substitua cada prefill de acordo com sua finalidade:

  • Formato de saída: use saídas estruturadas, ou ferramentas com campos enum para classificação.
  • Preâmbulos: peça no prompt do sistema uma resposta direta.
  • Continuações: mova-as para a mensagem do usuário, por exemplo “Sua resposta anterior foi interrompida e terminou com [previous_response]. Continue de onde parou.”
  • Lembretes de contexto: coloque-os no turno do usuário.

Mover o uso do computador para o conjunto de ferramentas

O Claude Haiku 4.5 oferece suporte a uso do computador por meio da ferramenta computer_20250124, com o cabeçalho beta computer-use-2025-01-24. O Claude Haiku 5.5 oferece suporte a uso do computador por meio do conjunto de ferramentas computer_toolset_20260801. Uma requisição ao Claude Haiku 5.5 que declara computer_20250124 retorna um erro 400.

Para migrar uma integração para o conjunto de ferramentas, remova o cabeçalho beta computer-use-2025-01-24 e substitua a entrada de tools por {"type": "computer_toolset_20260801"}. Em seguida, faça as outras alterações na requisição e no loop do agente descritas em Migrar de computer_20251124. Faça o despacho com base em name e toolset_name de cada bloco tool_use membro, em vez de input.action. Trate todos esses blocos em um turno e repita toolset_name nos resultados. O zoom vem ativado por padrão no conjunto de ferramentas; se seu ambiente não o implementa, adicione "configs": {"zoom": {"enabled": false}}. Se você envia o cabeçalho beta fine-grained-tool-streaming-2025-05-14, remova-o. Junto com uma entrada de conjunto de ferramentas, ele retorna um erro 400.

No Amazon Bedrock, o Claude Haiku 5.5 também aceita a ferramenta computer_20251124 com o cabeçalho beta computer-use-2025-11-24.

O Claude Haiku 5.5 oferece suporte à ferramenta de uso do navegador (browser_toolset_20260801) para tarefas dentro de páginas da web. O Claude Haiku 4.5 não oferece suporte a ela.

Reproduzir blocos de pensamento por meio da conta que os produziu

Os blocos de pensamento do Claude Haiku 5.5 funcionam apenas na conta que os produziu ou em uma conta vinculada a ela. Quando outra conta envia um desses blocos, a API descarta o bloco antes que o modelo o receba, e a requisição é bem-sucedida sem esse raciocínio. Isso afeta códigos que armazenam conversas e as reproduzem por meio de uma conta diferente, por exemplo, um serviço que atende vários clientes a partir de um único armazenamento de conversas. Reproduza cada conversa por meio da conta que a produziu. Consulte Contas e plataformas de nuvem.

Manter os turnos anteriores inalterados

Mantenha as conversas somente com acréscimos (append-only). Um bloco de pensamento do Claude Haiku 5.5 permanece válido apenas enquanto tudo o que foi enviado antes dele permanecer inalterado: o prompt system, as tools e todas as mensagens anteriores.

Não passar no “prefix check” (verificação de prefixo) pode ou não resultar em um erro 400. Para identificar e tratar ambos os casos, consulte Verificações de prefixo em blocos de pensamento.

Para saber quais alterações acionam o erro e o que fazer em vez disso, consulte Se o seu código altera o prompt do sistema, as ferramentas ou o histórico.

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

O Claude Haiku 3.5 está desativado na Claude API, no Amazon Bedrock e no Claude Models on Google Cloud (Google managed). O Claude Haiku 3 está desativado na Claude API e no Claude Models on Google Cloud (Google managed). Consulte Descontinuações de modelos.

A partir de qualquer um desses modelos, primeiro aplique todas as seções anteriores e, em seguida, estas alterações:

  • ID do modelo: Substitua claude-3-5-haiku-20241022, seu alias claude-3-5-haiku-latest ou claude-3-haiku-20240307 por claude-haiku-5-5. No Claude Models on Google Cloud (Google managed), substitua claude-3-5-haiku@20241022 por claude-haiku-5-5. No Amazon Bedrock, use o ID do Claude Haiku 5.5 de Usar o ID do modelo Claude Haiku 5.5.
  • Execução de código: O Claude Haiku 5.5 aceita code_execution_20250825 e versões posteriores. Se você usa a versão somente para Python code_execution_20250522, migre para uma delas. Consulte Atualizar para a versão mais recente da ferramenta.
  • Editor de texto: Se você usa a ferramenta de edição de texto, migre para text_editor_20250728 (nome da ferramenta str_replace_based_edit_tool), que não tem o comando undo_edit. Consulte Ferramenta de edição de texto.
  • Motivos de parada: Trate refusal e model_context_window_exceeded. Consulte Motivos de parada e fallback.
  • Quebras de linha finais: O Claude 4.5 e modelos posteriores mantêm quebras de linha finais nos parâmetros de string das chamadas de ferramentas. Se seu código compara essas strings exatamente, leve-as em conta.
  • Prompts: O Claude 4 e modelos posteriores têm um estilo de comunicação mais conciso e direto e precisam de instruções explícitas. Revise seus prompts com base em Prompting do Claude Haiku 5.5 e em Melhores práticas de prompting.

Esta página foi útil?