---
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: 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.
---

<Note>
  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.
</Note>

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

```text
/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](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#migrating-from-haiku-35). Para subir para um modelo Sonnet ou Opus em vez disso, consulte [Guias de migração](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 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](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 [Recontar 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 [Configurar 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` em vez disso. Consulte [Configurar 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 [Remover 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 em vez disso. Consulte [Substituir o preenchimento prévio do assistente](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#replace-assistant-prefill).
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](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 [Reproduzir 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 [Manter 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 ele não tem 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 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](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#safeguard-refusals).

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 é 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](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#migrating-from-haiku-35).
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.

| 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` |
| Claude Models on Google Cloud (Anthropic managed) | `claude-haiku-4-5-20251001` | `claude-haiku-5-5` |
| Claude Models on Google Cloud (Google managed) | `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.

## 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](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 do Claude Haiku 5.5, incluindo seus preços mais altos para prompts longos. Consulte [Preços](https://platform.claude.com/docs/pt-BR/about-claude/pricing) e [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 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](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.

## 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:

```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 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](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) 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](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 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](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 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:

| Troca | Manté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 anterior | Sim |
| Para o Claude Haiku 5.5, a partir de qualquer outro modelo | Nã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.2 | Sim, somente na Claude API e no Claude Models on Google Cloud (Google managed) |
| Do Claude Haiku 5.5 para qualquer outro modelo | Não |

Consulte [Trocar de modelo e voltar](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#switching-models). Para trocas que não envolvem o Claude Haiku 5.5, consulte [Quais trocas de modelo mantêm o raciocínio na Claude API](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#which-model-switches-keep-reasoning).

## 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](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs), 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](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`. 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`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#migrate-from-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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool) (`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](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#account-bound-thinking).

## 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](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking/prefix-checks#prefix-check)) pode ou não resultar em um [erro 400](https://platform.claude.com/docs/pt-BR/api/errors#thinking-block-conversation-mismatch). Para identificar e tratar ambos os casos, consulte [Verificações de prefixo em blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking/prefix-checks).

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](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking/prefix-checks#what-to-check).

## 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](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 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](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 versão somente para Python `code_execution_20250522`, 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 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](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 [Motivos de parada e fallback](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 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](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5) e em [Melhores práticas de prompting](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices).
