Accueil / L'API Claude pour ceux qui construisent

Recevoir la réponse au fil de l'eau

Le mode flux garde une seule connexion HTTP ouverte et livre le texte par fragments au fur et à mesure de sa génération, et le décompte cumulatif de jetons se lit dans le dernier événement message_delta reçu, jamais dans l'événement final message_stop.

Une réponse de l'API Messages arrive normalement d'un seul bloc, une fois que le modèle a fini de générer tout le texte. Le mode flux change ce comportement : la même connexion HTTP reste ouverte, et le serveur livre le texte par fragments, au fur et à mesure que le modèle le produit, sans attendre la fin de la génération.

La séquence exacte des événements

Un flux commence par un événement message_start, qui porte un objet message dont le champ content est encore vide à ce stade. Pour chaque bloc de contenu généré, un événement content_block_start ouvre le bloc, un ou plusieurs événements content_block_delta portent les fragments de texte reçus, puis un événement content_block_stop referme ce bloc. Une fois tous les blocs de la réponse terminés, un ou plusieurs événements message_delta arrivent, suivis d'un événement message_stop qui clôt la connexion. Des événements ping peuvent apparaître à tout moment dans le flux sans porter d'information utile, et un événement error signale un incident survenu côté serveur.

Où se trouve le décompte de jetons

Le décompte de jetons consommés par la requête est cumulatif d'un événement message_delta au suivant, et il vit dans le champ usage de cet événement, jamais dans message_stop lui même. Un code qui attend l'événement final pour lire ce décompte le cherche donc au mauvais endroit : il faut conserver le dernier message_delta reçu, juste avant l'arrêt du flux, et lire son champ usage à ce moment là. Cette nuance sépare une implémentation qui affiche un décompte de jetons correct d'une implémentation qui affiche un décompte figé à zéro ou manquant.

Le fragment suivant lit ces deux types d'événements à partir d'une requête construite comme la porte d'entrée unique de l'API. Il fabrique sa propre demande courte et ne dépend d'aucun fichier externe pour fonctionner.

import anthropic

client = anthropic.Anthropic()

texte_recu = ""
jetons_cumules = 0

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=200,
    messages=[{"role": "user", "content": "Ecris un haiku sur la pluie."}],
) as flux:
    for evenement in flux:
        if evenement.type == "content_block_delta" and evenement.delta.type == "text_delta":
            texte_recu += evenement.delta.text
            print(evenement.delta.text, end="", flush=True)
        if evenement.type == "message_delta":
            jetons_cumules = evenement.usage.output_tokens

print("\njetons de sortie cumules :", jetons_cumules)

Le texte s'affiche fragment par fragment dès sa réception, et la variable jetons_cumules ne se stabilise à sa valeur finale qu'après le dernier message_delta, avant que message_stop ne mette fin à la boucle. Une implémentation qui lirait ce compteur uniquement sur message_stop y trouverait un événement sans champ usage. Le fragment vérifie aussi le type exact du delta avant d'en lire le texte, puisqu'un content_block_delta peut porter un signature_delta plutôt qu'un text_delta lorsque le modèle produit un bloc de réflexion, un réglage actif par défaut sur Claude Sonnet 5.