---
title: Guia de migração para o Claude Haiku 5.5
url: https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide
description: Mude 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 de modelo, configurações que retornam erros, mudanças no pensamento e uma checklist para cada modelo de origem.
---
Este guia aborda a migração de código da [Messages API](https://platform.claude.com/docs/pt-BR/build-with-claude/working-with-messages). Se você usa o [Claude Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview), nenhuma alteração além da atualização do nome do modelo é necessária.
**Automatize sua migração com a skill Claude API.** No Claude Code, execute `/claude-api migrate` para invocar a [skill Claude API](https://platform.claude.com/docs/pt-BR/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model) incluída. Ela funciona com qualquer modelo Claude atual como destino:
Deixe o Claude Code migrar seu código para você
```text
/claude-api migrate este projeto para claude-haiku-5-5
```
A skill aplica a troca do ID do modelo e, conforme necessário, as alterações incompatíveis de parâmetros, a substituição de prefill e a calibração de esforço 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 conferir manualmente. Ela pede que você confirme o escopo da migração (todo o diretório de trabalho, 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 do Claude Platform on AWS e ajusta os formatos de ID de modelo e as alterações de recursos para essas plataformas.
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](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#migrating-from-haiku-35). Para migrar para um modelo Sonnet ou Opus, consulte [Atualizar entre versões de modelo](https://platform.claude.com/docs/pt-BR/about-claude/models/migration-guide). Para saber por quanto tempo o Claude Haiku 4.5 permanece disponível, consulte [Descontinuações de modelos](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations).
## Checklist de migração por modelo de origem
Percorra os grupos de cima para baixo e pare após aquele 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 origem
1. Substitua o ID do modelo pelo ID do Claude Haiku 5.5 para sua plataforma. Consulte [Use o ID do modelo Claude Haiku 5.5](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#use-the-claude-haiku-5-5-model-id).
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 [Reconte os tokens](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#recount-tokens).
3. Se suas requisições enviam `thinking: {"type": "enabled", "budget_tokens": N}`, altere `thinking` para `{"type": "adaptive"}`. Consulte [Configure o pensamento](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#configure-thinking).
4. Se seu código lê o primeiro bloco de conteúdo como a resposta, selecione os blocos por `type`. Consulte [Configure o pensamento](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#configure-thinking).
5. Remova `temperature`, `top_p` e `top_k` de suas requisições. Consulte [Remova os parâmetros de amostragem](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#remove-sampling-parameters).
6. Se suas requisições terminam `messages` com um turno do assistente para o modelo continuar, termine-as com um turno do usuário. Consulte [Substitua o prefill do assistente](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#replace-assistant-prefill).
7. Se você usa a ferramenta de uso de computador, substitua `computer_20250124`: na Claude API e no Google Cloud, pelo toolset `computer_toolset_20260801`; no Amazon Bedrock, por `computer_20251124` e o cabeçalho beta `computer-use-2025-11-24`. Consulte [Migre o uso de computador para o toolset](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#computer-use-toolset).
8. Se você reproduz conversas armazenadas por meio de uma conta diferente, reproduza cada uma por meio da conta que a produziu. Consulte [Reproduza blocos de pensamento por meio da conta que os produziu](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#replay-thinking-blocks-through-the-producing-account).
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 [Mantenha os turnos anteriores inalterados](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#keep-earlier-turns-unchanged).
10. Trate `stop_reason: "refusal"`. O Claude Haiku 5.5 executa classificadores de segurança que podem recusar uma requisição, e não possui fallback no lado do servidor. Consulte [Recusas de salvaguarda](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#safeguard-refusals).
11. Se você usa [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs) (`output_config.format` ou ferramentas com `strict: true`) no Amazon Bedrock, descreva o formato no prompt ou use uma ferramenta sem `strict`, e valide a saída no seu código. Saídas estruturadas não estão disponíveis para o Claude Haiku 5.5 no Amazon Bedrock.
Se sua organização tem um compromisso de [Priority Tier](https://platform.claude.com/docs/pt-BR/api/service-tiers#supported-models) no Claude Haiku 4.5, planeje a capacidade separadamente: o Priority Tier não é suportado no Claude Haiku 5.5.
### Claude Haiku 3.5 ou anterior
1. Substitua o ID de modelo do Claude Haiku 3.5 ou do 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](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#migrating-from-haiku-35).
2. Se você usa a ferramenta legada `code_execution_20250522`, migre para `code_execution_20250825` ou posterior.
3. Se você usa a ferramenta de editor 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 parâmetros de string de chamadas de ferramenta, leve em conta quebras de linha finais.
6. Revise seus prompts.
## Use 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.
| Plataforma | Claude Haiku 4.5 | Claude Haiku 5.5 |
| ---------------------- | ------------------------------------------------- | ---------------------------- |
| Claude API | `claude-haiku-4-5-20251001` ou `claude-haiku-4-5` | `claude-haiku-5-5` |
| Amazon Bedrock | `anthropic.claude-haiku-4-5` | `anthropic.claude-haiku-5-5` |
| Claude Platform on AWS | `claude-haiku-4-5` | `claude-haiku-5-5` |
| Google Cloud | `claude-haiku-4-5@20251001` | `claude-haiku-5-5` |
| Microsoft Foundry | `claude-haiku-4-5` | `claude-haiku-5-5` |
`claude-haiku-5-5` é um ID de modelo fixo, sem sufixo de data e sem alias separado.
## Reconte os tokens
O Claude Haiku 5.5 usa o mesmo "tokenizer" (tokenizador) mais recente do Claude 4.7 e de modelos posteriores. Como em todos os modelos que usam esse tokenizador, o mesmo texto de entrada produz aproximadamente 30% 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 de `usage` e os resultados da [contagem de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting) 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](https://platform.claude.com/docs/pt-BR/about-claude/pricing) do Claude Haiku 5.5, incluindo seus preços mais altos para prompts longos. Consulte [Preços de contexto longo](https://platform.claude.com/docs/pt-BR/about-claude/pricing#long-context-pricing).
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 de 4.784 tokens visuais. O Claude Haiku 4.5 e os modelos Haiku anteriores usam o nível padrão, que reduz imagens acima de 1.568 pixels no lado maior ou de 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](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size).
Conte seus prompts com `model` definido como `claude-haiku-5-5` em vez de reutilizar contagens medidas no Claude Haiku 4.5.
## Configure 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, portanto 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:
```json
{
"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:
```json
{
"model": "claude-haiku-5-5",
"max_tokens": 16000,
"thinking": { "type": "adaptive" },
"output_config": { "effort": "medium" },
"messages": [{ "role": "user", "content": "..." }]
}
```
O pensamento adaptativo é 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 ["effort" (esforço)](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) como alavanca: onde o Claude Haiku 4.5 era executado 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 sobre prompts, consulte [Use o esforço para controlar o pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking). 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](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) 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 mantinha apenas os do turno mais recente. Conversas com vários turnos, portanto, 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](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing#thinking-block-clearing). Consulte [Preservação de blocos de pensamento por modelo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-block-preservation-by-model).
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 retornava 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.
O Claude Haiku 5.5 lê blocos de pensamento do Claude Sonnet 5, do Claude Opus 4.8, do Claude Haiku 4.5 e de modelos anteriores, então uma conversa que você muda do Claude Haiku 4.5 para o Claude Haiku 5.5 mantém seu raciocínio. Ele não lê blocos do Claude Opus 5, do Claude Opus 5.5, do Claude Sonnet 5.5 nem de qualquer modelo Claude Fable ou Claude Mythos; a API os descarta sem erro. Na Claude API e no Google Cloud, o Claude Opus 5.5 e o Claude Sonnet 5.5 leem os blocos do Claude Haiku 5.5. Consulte [Trocar de modelo no meio da conversa](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#switching-models).
## Remova os parâmetros de amostragem
O Claude Haiku 4.5 aceita `temperature`, `top_p` e `top_k`. No Claude Haiku 5.5, omita os três e use prompts para orientar o comportamento do modelo. Se uma requisição incluir `temperature`, ele deve ser `1`. Se incluir `top_p`, ele deve ser `0.99`, seu valor padrão. Qualquer outro valor de `temperature` ou `top_p` retorna um erro 400, incluindo um `top_p` igual a `1`. O mesmo acontece com qualquer valor de `top_k` e com uma requisição que inclua tanto `temperature` quanto `top_p`.
## Substitua o prefill 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](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs), ou ferramentas com campos enum para classificação. No Amazon Bedrock, saídas estruturadas não estão disponíveis para o Claude Haiku 5.5. Nesse caso, descreva o formato no prompt ou use uma ferramenta sem `strict`, e valide a saída no seu código.
* **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.
## Migre o uso de computador para o toolset
O Claude Haiku 4.5 suporta o [uso de computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool) por meio da ferramenta `computer_20250124`, com o cabeçalho beta `computer-use-2025-01-24`. Na Claude API e no Google Cloud, o Claude Haiku 5.5 suporta o uso de computador apenas por meio do toolset `computer_toolset_20260801`, e uma requisição que declara `computer_20250124` retorna um erro 400. No Amazon Bedrock, o Claude Haiku 5.5 também não aceita `computer_20250124`; use a versão de ferramenta `computer_20251124` com o cabeçalho beta `computer-use-2025-11-24`.
Para migrar uma integração para o toolset, remova o cabeçalho beta `computer-use-2025-01-24` e substitua a entrada em `tools` por `{"type": "computer_toolset_20260801"}`. Em seguida, faça as demais alterações na requisição e no loop do agente descritas em [Migrar de `computer_20251124`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124): despache 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 toolset; 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 toolset, ele retorna um erro 400. Para outras plataformas, consulte a seção [Compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#compatibility) da ferramenta de uso de computador.
Na Claude API e no Google Cloud, o Claude Haiku 5.5 também suporta a [ferramenta de uso do navegador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool) (`browser_toolset_20260801`) para tarefas dentro de páginas web. O Claude Haiku 4.5 não a suporta.
## Reproduza 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 veja, e a requisição é bem-sucedida sem esse raciocínio. Isso afeta código que armazena conversas e as reproduz 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 [Os blocos de pensamento permanecem com a conta que os produziu](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#account-bound-thinking).
## Mantenha os turnos anteriores inalterados
Um bloco de pensamento do Claude Haiku 5.5 permanece válido apenas enquanto tudo o que foi enviado antes dele permanecer inalterado: uma requisição que envia um bloco de pensamento de volta após uma alteração em `system`, `tools` ou `messages` anteriores retorna um erro 400. O Claude Haiku 4.5 não executa essa verificação. Mantenha as conversas somente com acréscimos. Em contas criadas antes de 31 de agosto de 2026, 00:00 UTC, o erro ocorre apenas em requisições que definem `thinking.block_binding.prefix_mismatch_behavior`. Para saber quais alterações acionam o erro e o que fazer em vez disso, consulte [Quem precisa mudar alguma coisa](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#who-is-affected).
## 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 e no Amazon Bedrock, e o Claude Haiku 3 está desativado na Claude API e no Google Cloud. Requisições a um modelo desativado falham. O Google Cloud lista o Claude Haiku 3.5 como descontinuado e disponível apenas para clientes existentes. Consulte [Descontinuações de modelos](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations).
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 Google Cloud, substitua `claude-3-5-haiku@20241022` por `claude-haiku-5-5`. No Amazon Bedrock, use o ID do Claude Haiku 5.5 de [Use o ID do modelo Claude Haiku 5.5](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#use-the-claude-haiku-5-5-model-id).
* **Execução de código:** O Claude Haiku 5.5 aceita `code_execution_20250825` e versões posteriores. Se você usa a ferramenta legada `code_execution_20250522`, exclusiva para Python, migre para uma delas. Consulte [Atualizar para a versão mais recente da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version).
* **Editor de texto:** Se você usa a ferramenta de editor 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 editor de texto](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/text-editor-tool).
* **Motivos de parada:** Trate `refusal` e `model_context_window_exceeded`. Consulte [Tratando motivos de parada](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons).
* **Quebras de linha finais:** O Claude 4.5 e modelos posteriores mantêm quebras de linha finais em parâmetros de string de chamadas de ferramenta. 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](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5) e nas [melhores práticas de prompting](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices).