Apprenez à diffuser des messages de manière incrémentielle en utilisant des événements envoyés par le serveur (SSE) avec l’API Claude.
Lors de la création d’un Message, vous pouvez définir "stream": true pour diffuser la réponse de manière incrémentielle en utilisant des événements envoyés par le serveur (SSE).
Nos SDK Python et TypeScript offrent plusieurs façons de faire du streaming. Le SDK Python permet les flux synchrones et asynchrones. Consultez la documentation de chaque SDK pour plus de détails.
import anthropicclient = anthropic.Anthropic()with client.messages.stream( max_tokens=1024, messages=[{"role":"user","content":"Hello"}], model="claude-opus-4-1-20250805",)as stream:for text in stream.text_stream:print(text, end="", flush=True)
Chaque événement envoyé par le serveur inclut un type d’événement nommé et des données JSON associées. Chaque événement utilisera un nom d’événement SSE (par exemple event: message_stop), et inclura le type d’événement correspondant dans ses données.
Chaque flux utilise le flux d’événements suivant :
message_start : contient un objet Message avec un content vide.
Une série de blocs de contenu, chacun ayant un content_block_start, un ou plusieurs événements content_block_delta, et un événement content_block_stop. Chaque bloc de contenu aura un index qui correspond à son index dans le tableau content du Message final.
Un ou plusieurs événements message_delta, indiquant les changements de niveau supérieur à l’objet Message final.
Un événement final message_stop.
Les comptes de jetons affichés dans le champ usage de l’événement message_delta sont cumulatifs.
Nous pouvons occasionnellement envoyer des erreurs dans le flux d’événements. Par exemple, pendant les périodes d’utilisation intensive, vous pourriez recevoir une overloaded_error, qui correspondrait normalement à un HTTP 529 dans un contexte non-streaming :
Conformément à notre politique de versioning, nous pouvons ajouter de nouveaux types d’événements, et votre code devrait gérer les types d’événements inconnus de manière gracieuse.
Les deltas pour les blocs de contenu tool_use correspondent aux mises à jour pour le champ input du bloc. Pour supporter une granularité maximale, les deltas sont des chaînes JSON partielles, alors que le tool_use.input final est toujours un objet.
Vous pouvez accumuler les deltas de chaîne et analyser le JSON une fois que vous recevez un événement content_block_stop, en utilisant une bibliothèque comme Pydantic pour faire de l’analyse JSON partielle, ou en utilisant nos SDK, qui fournissent des assistants pour accéder aux valeurs incrémentales analysées.
Un delta de bloc de contenu tool_use ressemble à :
Note : Nos modèles actuels ne supportent que l’émission d’une clé complète et d’une propriété de valeur de input à la fois. Ainsi, lors de l’utilisation d’outils, il peut y avoir des délais entre les événements de streaming pendant que le modèle travaille. Une fois qu’une clé et une valeur input sont accumulées, nous les émettons comme plusieurs événements content_block_delta avec du json partiel fragmenté afin que le format puisse automatiquement supporter une granularité plus fine dans les futurs modèles.
Lors de l’utilisation de la réflexion étendue avec le streaming activé, vous recevrez le contenu de réflexion via des événements thinking_delta. Ces deltas correspondent au champ thinking des blocs de contenu thinking.
Pour le contenu de réflexion, un événement spécial signature_delta est envoyé juste avant l’événement content_block_stop. Cette signature est utilisée pour vérifier l’intégrité du bloc de réflexion.
Un delta de réflexion typique ressemble à :
Delta de réflexion
event: content_block_deltadata:{"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"Let me solve this step by step:\n\n1. First break down 27 * 453"}}
Nous recommandons fortement d’utiliser nos SDK clients lors de l’utilisation du mode streaming. Cependant, si vous construisez une intégration API directe, vous devrez gérer ces événements vous-même.
Une réponse de flux est composée de :
Un événement message_start
Potentiellement plusieurs blocs de contenu, chacun contenant :
Un événement content_block_start
Potentiellement plusieurs événements content_block_delta
Un événement content_block_stop
Un événement message_delta
Un événement message_stop
Il peut y avoir des événements ping dispersés dans la réponse également. Voir Types d’événements pour plus de détails sur le format.
L’utilisation d’outils supporte maintenant le streaming à granularité fine pour les valeurs de paramètres comme fonctionnalité bêta. Pour plus de détails, voir Streaming d’outils à granularité fine.
Dans cette requête, nous demandons à Claude d’utiliser un outil pour nous dire la météo.
curl https://api.anthropic.com/v1/messages \-H"content-type: application/json"\-H"x-api-key: $ANTHROPIC_API_KEY"\-H"anthropic-version: 2023-06-01"\-d '{"model":"claude-opus-4-1-20250805","max_tokens":1024,"tools":[{"name":"get_weather","description":"Get the current weather in a given location","input_schema":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"}},"required":["location"]}}],"tool_choice":{"type":"any"},"messages":[{"role":"user","content":"What is the weather like in San Francisco?"}],"stream":true}'
Requête de streaming avec utilisation d’outil de recherche web
Dans cette requête, nous demandons à Claude de rechercher sur le web des informations météorologiques actuelles.
curl https://api.anthropic.com/v1/messages \--header"x-api-key: $ANTHROPIC_API_KEY"\--header"anthropic-version: 2023-06-01"\--header"content-type: application/json"\--data\'{"model":"claude-opus-4-1-20250805","max_tokens":1024,"stream": true,"tools":[{"type":"web_search_20250305","name":"web_search","max_uses":5}],"messages":[{"role":"user","content":"What is the weather like in New York City today?"}]}'
Response
event: message_startdata:{"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-4-1-20250805","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":2679,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":3}}}event: content_block_startdata:{"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}event: content_block_deltadata:{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"I'll check"}}event: content_block_deltadata:{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the current weather in New York City for you"}}event: pingdata:{"type":"ping"}event: content_block_deltadata:{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"."}}event: content_block_stopdata:{"type":"content_block_stop","index":0}event: content_block_startdata:{"type":"content_block_start","index":1,"content_block":{"type":"server_tool_use","id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","name":"web_search","input":{}}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"query"}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\":"}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"weather"}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" NY"}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"C to"}}event: content_block_deltadata:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"day\"}"}}event: content_block_stopdata:{"type":"content_block_stop","index":1}event: content_block_startdata:{"type":"content_block_start","index":2,"content_block":{"type":"web_search_tool_result","tool_use_id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","content":[{"type":"web_search_result","title":"Weather in New York City in May 2025 (New York) - detailed Weather Forecast for a month","url":"https://world-weather.info/forecast/usa/new_york/may-2025/","encrypted_content":"Ev0DCioIAxgCIiQ3NmU4ZmI4OC1k...","page_age":null},...]}}event: content_block_stopdata:{"type":"content_block_stop","index":2}event: content_block_startdata:{"type":"content_block_start","index":3,"content_block":{"type":"text","text":""}}event: content_block_deltadata:{"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"Here's the current weather information for New York"}}event: content_block_deltadata:{"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" City:\n\n# Weather"}}event: content_block_deltadata:{"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" in New York City"}}event: content_block_deltadata:{"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"\n\n"}}...event: content_block_stopdata:{"type":"content_block_stop","index":17}event: message_deltadata:{"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":10682,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":510,"server_tool_use":{"web_search_requests":1}}}event: message_stopdata:{"type":"message_stop"}
Lorsqu’une requête de streaming est interrompue en raison de problèmes de réseau, de délais d’attente ou d’autres erreurs, vous pouvez récupérer en reprenant là où le flux a été interrompu. Cette approche vous évite de retraiter toute la réponse.
La stratégie de récupération de base implique :
Capturer la réponse partielle : Sauvegarder tout le contenu qui a été reçu avec succès avant que l’erreur ne se produise
Construire une requête de continuation : Créer une nouvelle requête API qui inclut la réponse partielle de l’assistant comme le début d’un nouveau message d’assistant
Reprendre le streaming : Continuer à recevoir le reste de la réponse là où elle a été interrompue
Utiliser les fonctionnalités du SDK : Exploiter les capacités intégrées d’accumulation de messages et de gestion d’erreurs du SDK
Gérer les types de contenu : Être conscient que les messages peuvent contenir plusieurs blocs de contenu (text, tool_use, thinking). Les blocs d’utilisation d’outils et de réflexion étendue ne peuvent pas être partiellement récupérés. Vous pouvez reprendre le streaming à partir du bloc de texte le plus récent.
