Guide de migration vers Claude Haiku 5.5

Ce guide explique comment faire passer du code qui appelle Claude Haiku 4.5 à Claude Haiku 5.5. Pour passer plutôt à un modèle Sonnet ou Opus, consultez Mettre à niveau entre les versions de modèles. Pour savoir combien de temps Claude Haiku 4.5 reste disponible, consultez Dépréciations de modèles.

Liste de contrôle de migration

Chaque élément correspond à une modification à apporter au code qui appelle Claude Haiku 4.5.

1. Remplacez l'identifiant de modèle par l'identifiant Claude Haiku 5.5 de votre plateforme. Consultez Utiliser l'identifiant de modèle Claude Haiku 5.5.
2. Recomptez vos prompts, et revoyez les limites max_tokens et les estimations de coûts, car le même texte compte davantage de tokens. Consultez Recompter les tokens.
3. Si vos requêtes envoient thinking: {"type": "enabled", "budget_tokens": N}, remplacez thinking par {"type": "adaptive"}. Consultez Configurer la réflexion.
4. Si votre code lit le premier bloc de contenu comme étant la réponse, sélectionnez plutôt les blocs par type. Consultez Configurer la réflexion.
5. Supprimez temperature, top_p et top_k de vos requêtes. Consultez Supprimer les paramètres d'échantillonnage.
6. Si vos requêtes terminent messages par un tour de l'assistant que le modèle doit poursuivre, terminez-les plutôt par un tour de l'utilisateur. Consultez Remplacer le préremplissage de l'assistant.
7. Si vous recourez à l'utilisation de l'ordinateur sur l'API Claude ou Google Cloud, passez de computer_20250124 à l'ensemble d'outils computer_toolset_20260801. Consultez Faire passer l'utilisation de l'ordinateur à l'ensemble d'outils.
8. Si vous rejouez des conversations stockées via un autre compte, rejouez chacune d'elles via le compte qui l'a produite. Consultez Rejouer les blocs de réflexion via le compte qui les a produits.
9. Si votre code modifie system, tools ou des messages antérieurs entre les requêtes d'une conversation et renvoie des blocs de réflexion, conservez la conversation en ajout seul. Consultez Conserver les tours précédents inchangés.
10. Gérez stop_reason: "refusal". Claude Haiku 5.5 exécute des classificateurs de sécurité qui peuvent refuser une requête, et il ne dispose d'aucun repli côté serveur. Consultez Refus des mesures de protection.

Si votre organisation dispose d'un engagement Priority Tier sur Claude Haiku 4.5, planifiez la capacité séparément : Priority Tier n'est pas pris en charge sur Claude Haiku 5.5.

Utiliser l'identifiant de modèle Claude Haiku 5.5

Remplacez l'identifiant de modèle Claude Haiku 4.5 par l'identifiant Claude Haiku 5.5 de votre plateforme.

claude-haiku-5-5 est un identifiant de modèle fixe, sans suffixe de date ni alias distinct.

Recompter les tokens

Claude Haiku 5.5 utilise le même tokenizer plus récent que Claude 4.7 et les modèles ultérieurs. Comme pour tous les modèles qui utilisent ce tokenizer, le même texte d'entrée produit environ 30 % de tokens de plus sur Claude Haiku 5.5 que sur Claude Haiku 4.5. L'augmentation exacte dépend du contenu. Les requêtes, les réponses et les événements de streaming conservent la même forme. Ce qui change, c'est tout ce que vous mesurez ou budgétez en tokens :

• Les champs usage et les résultats du comptage de tokens sont plus élevés pour le même texte.
• Un nombre donné de tokens contient moins de texte.
• Une limite max_tokens ajustée pour Claude Haiku 4.5 peut tronquer une sortie équivalente.
• Les estimations de coûts établies à partir des nombres de tokens de Claude Haiku 4.5 doivent être recalculées avec les nombres de Claude Haiku 5.5 et ses tarifs.

Comptez vos prompts avec model défini sur claude-haiku-5-5 plutôt que de réutiliser les nombres mesurés sur Claude Haiku 4.5.

Configurer la réflexion

Claude Haiku 5.5 configure la réflexion différemment de Claude Haiku 4.5. Une valeur thinking de {"type": "enabled", "budget_tokens": N} renvoie une erreur 400 ; une requête qui l'envoie a donc besoin d'une nouvelle valeur thinking.

Avant, une requête à Claude Haiku 4.5 définissait thinking sur enabled avec un budget de tokens :

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

Après, la même requête à Claude Haiku 5.5 utilise la réflexion adaptative. La valeur thinking change, et output_config.effort définit le degré de réflexion du modèle :

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

La réflexion adaptative est activée par défaut ; une réponse peut donc commencer par un ou plusieurs blocs thinking même lorsque la requête ne définit pas thinking. Laissez thinking non défini ou définissez-le sur {"type": "adaptive"}, et utilisez l'effort comme levier : là où Claude Haiku 4.5 fonctionnait sans réflexion, ou avec un petit budget pour économiser des tokens, choisissez un niveau d'effort plus faible. À un niveau plus faible, le modèle réfléchit moins, et il peut ignorer entièrement la réflexion pour les requêtes plus simples. Pour des conseils de prompting, consultez Utiliser l'effort pour contrôler la réflexion. Sélectionnez les blocs de contenu par leur champ type plutôt que par leur position, et renvoyez les blocs thinking sans modification avec les résultats d'outils.

Les « thinking tokens » (tokens de réflexion) sont comptabilisés dans max_tokens ; une requête avec un petit max_tokens peut donc s'arrêter avec stop_reason: "max_tokens" après un bloc thinking et avant tout texte. Si vous avez défini un petit max_tokens pour Claude Haiku 4.5, augmentez-le pour laisser de la place à la réflexion, ou choisissez un niveau d'effort plus faible.

Par défaut, Claude Haiku 5.5 renvoie chaque bloc thinking avec un champ thinking vide et uniquement une signature, là où Claude Haiku 4.5 renvoyait une réflexion résumée. Pour recevoir une réflexion résumée, définissez thinking: {"type": "adaptive", "display": "summarized"}.

Claude Haiku 5.5 accepte un tool_choice forcé (any ou un outil nommé), mais la réponse commence par l'appel d'outil et ne contient aucun bloc thinking. Pour permettre au modèle de réfléchir avant d'appeler un outil, utilisez tool_choice: {"type": "auto"} et indiquez dans le prompt quand utiliser l'outil.

Supprimer les paramètres d'échantillonnage

Claude Haiku 4.5 accepte temperature, top_p et top_k. Sur Claude Haiku 5.5, omettez ces trois paramètres et utilisez plutôt le prompting pour guider le comportement du modèle. Si une requête inclut temperature, sa valeur doit être 1. Si elle inclut top_p, sa valeur doit être 0.99, sa valeur par défaut. Toute autre valeur de temperature ou de top_p renvoie une erreur 400, y compris un top_p de 1. Il en va de même pour toute valeur de top_k, ainsi que pour une requête qui inclut à la fois temperature et top_p.

Remplacer le préremplissage de l'assistant

Un préremplissage est un tour final de l'assistant dans messages que le modèle poursuit. Claude Haiku 4.5 en accepte un lorsque la réflexion est désactivée. Claude Haiku 5.5 le rejette avec une erreur 400, même lorsque la réflexion est désactivée. Terminez messages par un tour de l'utilisateur, et remplacez chaque préremplissage selon son objectif :

• Format de sortie : utilisez les sorties structurées, ou des outils avec des champs enum pour la classification. Sur Claude dans Amazon Bedrock, qui ne prend pas en charge les sorties structurées, utilisez des outils.
• Préambules : demandez une réponse directe dans l'invite système.
• Continuations : déplacez-les dans le message de l'utilisateur, par exemple « Votre réponse précédente a été interrompue et s'est terminée par [previous_response]. Reprenez là où vous vous êtes arrêté. »
• Rappels de contexte : placez-les dans le tour de l'utilisateur.

Faire passer l'utilisation de l'ordinateur à l'ensemble d'outils

Claude Haiku 4.5 prend en charge l'utilisation de l'ordinateur via l'outil computer_20250124, avec l'en-tête bêta computer-use-2025-01-24. Sur l'API Claude et Google Cloud, Claude Haiku 5.5 prend en charge l'utilisation de l'ordinateur uniquement via l'ensemble d'outils computer_toolset_20260801, et une requête qui déclare computer_20250124 renvoie une erreur 400.

Pour migrer une intégration, supprimez l'en-tête bêta computer-use-2025-01-24 et remplacez l'entrée tools par {"type": "computer_toolset_20260801"}. Effectuez ensuite les autres modifications de requête et de boucle d'agent décrites dans Migrer depuis computer_20251124 : répartissez le traitement selon le name et le toolset_name de chaque bloc tool_use membre plutôt que selon input.action, traitez chacun de ces blocs dans un tour, et renvoyez toolset_name dans les résultats. Le zoom est activé par défaut dans l'ensemble d'outils ; si votre environnement ne l'implémente pas, ajoutez "configs": {"zoom": {"enabled": false}}. Si vous envoyez l'en-tête bêta fine-grained-tool-streaming-2025-05-14, supprimez-le. Associé à une entrée d'ensemble d'outils, il renvoie une erreur 400. Pour les autres plateformes, consultez la section Compatibilité de l'outil d'utilisation de l'ordinateur.

Sur l'API Claude et Google Cloud, Claude Haiku 5.5 prend également en charge l'outil d'utilisation du navigateur (browser_toolset_20260801) pour les tâches au sein de pages web. Claude Haiku 4.5 ne le prend pas en charge.

Rejouer les blocs de réflexion via le compte qui les a produits

Les blocs de réflexion de Claude Haiku 5.5 ne fonctionnent que dans le compte qui les a produits, ou dans un compte qui lui est lié. Lorsqu'un autre compte envoie l'un de ces blocs, l'API supprime le bloc avant que le modèle ne le voie, et la requête réussit sans ce raisonnement. Cela concerne le code qui stocke des conversations et les rejoue via un autre compte, par exemple un service qui sert plusieurs clients à partir d'un même stockage de conversations. Rejouez chaque conversation via le compte qui l'a produite. Consultez Les blocs de réflexion restent liés au compte qui les a produits.

Conserver les tours précédents inchangés

Un bloc de réflexion de Claude Haiku 5.5 ne reste valide que tant que tout ce qui a été envoyé avant lui reste inchangé : une requête qui renvoie un bloc de réflexion après une modification de system, de tools ou de messages antérieurs renvoie une erreur 400. Claude Haiku 4.5 n'effectue pas cette vérification. Conservez les conversations en ajout seul. Sur les comptes créés avant le 31 août 2026 à 00:00 UTC, l'erreur ne se produit que pour les requêtes qui définissent thinking.block_binding.prefix_mismatch_behavior. Pour connaître les modifications qui déclenchent l'erreur et ce qu'il faut faire à la place, consultez Qui doit modifier quelque chose.