Claude Message Threads API : guide des fils

L'API Claude Message Threads permet d'envoyer une longue conversation une seule fois, puis uniquement les nouveaux messages à chaque tour suivant. Ajoutez "thread": {"type": "create"} à la première requête Messages et l'en-tête bêta message-threads-2026-08-12 : l'API garde la conversation en mémoire et la requête suivante envoie moins de contenu (page Message threads d'Anthropic, 4 novembre 2026).

C'est une bêta sur tous les modèles. 17 identifiants de modèle peuvent l'utiliser, dont Claude Opus 5.5, que le code ci-dessous appelle. L'en-tête bêta accompagne chaque requête d'un fil.

Ce qu'un fil économise

Sans fil, chaque tour transporte tout l'historique : le prompt système, les définitions d'outils, chaque message précédent et chaque résultat d'outil. Un fil range cette conversation, réponse de Claude comprise, sous l'id de la réponse, et une requête continue n'envoie que ce qui s'est passé depuis (page Message threads, 4 novembre 2026). Moins de contenu à chaque tour.

Le cache de prompt aide la même conversation autrement. Un succès de cache rend l'entrée répétée moins chère : sur Opus 5.5, 0,20 USD par million de tokens contre 4 USD pour une entrée neuve (page des tarifs d'Anthropic, 4 novembre 2026). La requête transporte quand même cette entrée. Le fil réduit ce que vous envoyez ; le cache réduit le prix de ce qui se répète. Les longues sessions gagnent aux deux, et réduire la consommation de tokens de Claude Code couvre le côté contexte.

Les fils ne changent ni les tarifs ni les limites de débit (page Message threads, 4 novembre 2026). Les tarifs du moment sont sur tarifs.

Le cache reste à votre charge. Envoyez un cache_control au niveau supérieur de chaque requête et l'API l'applique au dernier bloc cachable des messages de cette requête. La limite de quatre points d'arrêt est une règle du cache de prompt à l'échelle de la plateforme, et le cache automatique en occupe un (page du cache de prompt d'Anthropic, 4 novembre 2026). Répartissez-les ainsi :

1. le cache_control au niveau supérieur, un point dans chaque requête du fil ;
2. un sur system, envoyé avec la requête create ;
3. un sur tools, aussi à la création ;
4. un sur le message le plus récent.

Les points d'arrêt posés sur des messages déjà stockés sortent de ce budget, puisqu'une requête continue n'envoie que les nouveaux messages. Une fois envoyé, un point d'arrêt reste où il est. Quand vous renvoyez une conversation, retirez les points des messages antérieurs et gardez-en un sur le dernier bloc (page Message threads, 4 novembre 2026).

Créer le premier tour, puis continuer

Trois étapes :

1. Placez votre clé Anthropic dans ANTHROPIC_API_KEY.
2. Envoyez la conversation complète, avec system et tools si vous les utilisez, plus "thread": {"type": "create"}.
3. Envoyez seulement les messages depuis la dernière réponse, plus "thread": {"type": "continue", "previous_message_id": "<previous id>"}, et laissez system et tools de côté.

Chaque requête porte l'en-tête bêta et anthropic-version: 2026-10-21, la version actuelle (page des versions d'Anthropic, 4 novembre 2026).

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "system": "You are a careful backend reviewer.",
    "messages": [
      {"role": "user", "content": "Read this design and list the risks."}
    ],
    "thread": {"type": "create"}
  }'

Gardez l'id de cette réponse. La requête suivante n'envoie que le nouveau message :

PREVIOUS_ID="<id from the previous response>"

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d @- <<JSON
{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Turn those risks into a checklist."}
  ],
  "thread": {"type": "continue", "previous_message_id": "$PREVIOUS_ID"}
}
JSON

Conservez l'id le plus récent de chaque réponse : un fil ne prend que des ajouts, chaque id de réponse se continue une seule fois, et la requête suivante doit utiliser le dernier (page Message threads, 4 novembre 2026).

S'il vous faut un autre moyen d'obtenir une clé API, OmniaKey vend un accès à l'API Claude avec les mêmes identifiants de modèle, donc le corps de la requête ne change pas. Les fils sont une bêta côté Anthropic : avant d'en dépendre en production, vérifiez que le relais que vous utilisez laisse passer le champ thread tel quel.

Le SDK Python suit les id pour vous. Créez un assistant avec client.beta.messages.thread(...), qui ne fait que préparer l'appel, puis envoyez chaque tour avec thread.send(). L'assistant ajoute l'en-tête bêta, crée au premier tour, continue avec les seuls nouveaux messages et renvoie une fois toute la conversation dans une nouvelle requête create quand une requête continue donne thread_not_found, thread_already_continued ou thread_continue_in_flight (page Message threads, 4 novembre 2026).

import anthropic

client = anthropic.Anthropic()  # lit ANTHROPIC_API_KEY

# L'assistant n'envoie encore rien ; il garde les champs réutilisés à chaque tour.
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="You are a careful backend reviewer.",
)

first = thread.send({"role": "user", "content": "Read this design and list the risks."})
print(first.id, first.stop_reason)

second = thread.send({"role": "user", "content": "Turn those risks into a checklist."})
print(second.id)  # la prochaine fois, reprendre depuis cet id

Nous n'avons pas exécuté ces requêtes contre l'API d'Anthropic ; la forme vient de la page Message threads d'Anthropic. Pour le streaming, thread.stream(...) et stream.get_final_message() donnent le même déroulé, et thread.previous_message_id renvoie l'id quand vous préférez le suivre vous-même.

Ce qu'il faut renvoyer, et ce qu'il ne faut jamais renvoyer

Envoyez les champs fixes avec les mêmes valeurs à chaque requête, system et tools seulement dans la requête create, et laissez les champs libres changer d'un tour à l'autre.

Le 400 d'un champ fixe modifié porte thread_fingerprint_mismatch, et le message liste les champs qui diffèrent. Pour changer l'une de ces valeurs, ouvrez un nouveau fil avec la conversation complète et la nouvelle valeur.

Si previous_message_id manque, la requête continue renvoie 400 avec un message dans le corps mais aucun error_code ; ajouter system ou tools produit le même effet. Une requête continue doit porter exactement les messages depuis la dernière réponse.

mcp_servers est fixe, mais les URL des serveurs et les jetons d'autorisation ne vivent que dans votre requête : envoyez donc la liste dans chaque requête qui utilise MCP ; un jeton peut changer entre deux requêtes. L'id du conteneur ne vit que dans votre requête lui aussi, alors envoyez container à chaque fois (page Message threads, 4 novembre 2026).

Le repli côté serveur se décide à la création : envoyez fallbacks dans chaque requête du fil ou dans aucune. La valeur peut changer entre les tours, mais ajouter ou retirer le champ renvoie thread_fingerprint_mismatch.

Expiration, renvoi et le 404

Un fil expire 5 minutes après sa dernière requête, et l'API le supprime au plus tard 1 heure après sa dernière utilisation. Chaque réponse stockée relance les 5 minutes. Les fils ne relèvent pas de la conservation nulle des données : la conversation, le prompt système et les outils restent en mémoire, chiffrés, et ne sont jamais écrits sur un stockage durable (page Message threads, 4 novembre 2026).

Aucun champ de la réponse ne dit si l'API a stocké un tour, ni en create ni en continue. Vous l'apprenez à la requête continue suivante : votre application reste la source de vérité et garde sa propre copie de chaque message (page Message threads, 4 novembre 2026).

Quand une requête continue renvoie 404 thread_not_found, envoyez la conversation complète dans une nouvelle requête create et reprenez depuis l'id de cette réponse. L'API renvoie le même 404 dans tous ces cas :

• le fil a expiré ;
• le tour précédent a été servi puis abandonné, par exemple un appel d'outil coupé par max_tokens ;
• un modèle de repli a écrit la réponse précédente ;
• la réponse précédente est encore en cours de génération ;
• la requête vient d'une autre organisation, d'un autre espace de travail, d'un autre utilisateur ou d'une autre clé d'espace de travail ;
• les nouveaux messages apportent du contenu absent de la conversation stockée, comme la première image d'une conversation qui n'en avait aucune.

Renvoyer la conversation complète est toujours sûr et répare chacun de ces cas.

Le streaming ajoute une règle : ne reprenez depuis l'id de la réponse qu'après message_stop, car une requête continue envoyée plus tôt peut renvoyer 404. Si le flux d'une requête continue s'interrompt avant message_stop, renvoyez la même requête continue, et renvoyez tout si cela donne thread_already_continued ou thread_continue_in_flight. L'assistant du SDK laisse le flux interrompu à votre retry.

Trois autres cas ont leur propre chemin :

• pause_turn : reprenez depuis l'id de cette réponse avec "messages": []. Si cela donne 404, renvoyez tout en incluant la réponse en pause.
• stop_reason: "refusal" : ouvrez un nouveau fil sans le tour qui l'a provoqué ; l'API détient peut-être déjà le tour refusé.
• une entrée fallback_message dans usage.iterations, ou dans le dernier message_delta d'un flux, signale une réponse de repli : renvoyez tout.

Erreurs

Les cinq erreurs de fil reviennent avant que le modèle tourne : la requête ne consomme pas de tokens et le fil garde son délai. error.type vaut invalid_request_error pour les 400 et not_found_error pour le 404 (page Message threads, 4 novembre 2026).

• 404, thread_not_found : l'API ne peut pas continuer ce fil. Envoyez la conversation complète dans une nouvelle requête create.
• 400, thread_fingerprint_mismatch : un champ fixe a changé par rapport à la valeur stockée avec le fil. Gardez-le identique ou ouvrez un nouveau fil.
• 400, thread_already_continued : cet id de réponse a déjà servi une fois. Reprenez depuis l'id le plus récent, et renvoyez tout si vous ne l'avez jamais reçu.
• 400, thread_continue_in_flight : un autre continue sur le même id tourne encore, souvent votre essai précédent. Laissez-le finir ou renvoyez tout.
• 400, thread_unsupported_request : la requête utilise une fonction ou un réglage d'organisation que les fils ne prennent pas en charge. error.details.unsupported nomme l'un de context_management, cache_control, fallbacks, hipaa ou inference_hooks ; cette liste peut s'allonger, donc si une valeur vous est inconnue, envoyez la conversation complète sans thread.

Message Batches refuse le champ thread (un élément de lot qui le porte échoue avec invalid_request_error), et le comptage de tokens comme la compaction renvoient 400 ; idem pour l'édition de contexte autre que clear_thinking_20251015 avec keep: "all". Les organisations prêtes pour HIPAA et celles qui activent Inference hooks sont exclues. Lister, lire et supprimer un fil n'existent pas dans l'API.

Questions fréquentes

Qu'est-ce que l'API Claude Message Threads ?

Une fonction bêta de l'API Messages qui stocke une conversation du côté d'Anthropic pour que les tours suivants n'envoient que les nouveaux messages. L'en-tête bêta est message-threads-2026-08-12, et chaque requête ajoute un objet thread dont type vaut create ou continue.

Les fils fonctionnent-ils avec le cache de prompt ?

Oui. Un fil ne met pas votre prompt en cache à votre place : envoyez un cache_control au niveau supérieur de chaque requête et tenez-vous à quatre points d'arrêt. Les points posés sur les messages stockés ne comptent pas ; celui du niveau supérieur et ceux sur system ou tools comptent.

Puis-je changer de modèle au milieu d'un fil ?

Un changement de modèle demande un nouveau fil. model est un champ fixe : une autre valeur renvoie 400 thread_fingerprint_mismatch. Ouvrez un nouveau fil avec la conversation complète et le nouveau modèle.

Pourquoi une requête continue renvoie-t-elle 400 sans error_code ?

Il manque previous_message_id, ou la requête contient system ou tools, même à null. Ces 400 portent un message et omettent error_code : lisez le texte.

Combien de temps dure un fil, et que se passe-t-il à l'expiration ?

Un fil expire 5 minutes après sa dernière requête et est supprimé au plus tard 1 heure après sa dernière utilisation. Ensuite, une requête continue renvoie 404 thread_not_found ; envoyez la conversation complète dans une nouvelle requête create et reprenez depuis son id.

Sources vérifiées

• Anthropic : message threads
• Anthropic : cache de prompt
• Anthropic : tarifs de l'API Claude
• Anthropic : versions de l'API