Inicio / La API de Claude para quienes construyen

Recibir la respuesta en streaming

El modo de streaming mantiene una única conexión HTTP abierta y entrega el texto por fragmentos a medida que se genera, y el recuento acumulado de tokens se lee en el último evento message_delta recibido, nunca en el evento final message_stop.

Una respuesta de la API Messages llega normalmente de un solo bloque, una vez que el modelo ha terminado de generar todo el texto. El modo de streaming cambia este comportamiento: la misma conexión HTTP permanece abierta, y el servidor entrega el texto por fragmentos, a medida que el modelo lo produce, sin esperar al final de la generación.

La secuencia exacta de los eventos

Un flujo comienza con un evento message_start, que lleva un objeto message cuyo campo content todavía está vacío en esta etapa. Para cada bloque de contenido generado, un evento content_block_start abre el bloque, uno o varios eventos content_block_delta llevan los fragmentos de texto recibidos, y luego un evento content_block_stop cierra ese bloque. Una vez terminados todos los bloques de la respuesta, llegan uno o varios eventos message_delta, seguidos de un evento message_stop que cierra la conexión. Pueden aparecer eventos ping en cualquier momento del flujo sin llevar información útil, y un evento error señala un incidente ocurrido del lado del servidor.

Dónde se encuentra el recuento de tokens

El recuento de tokens consumidos por la petición es acumulativo de un evento message_delta al siguiente, y vive en el campo usage de ese evento, nunca en message_stop mismo. Un código que espera el evento final para leer ese recuento lo busca entonces en el lugar equivocado: hay que conservar el último message_delta recibido, justo antes del cierre del flujo, y leer su campo usage en ese momento. Este matiz separa una implementación que muestra un recuento de tokens correcto de una implementación que muestra un recuento congelado en cero o ausente.

El siguiente fragmento lee estos dos tipos de eventos a partir de una petición construida como la puerta de entrada única de la API. Fabrica su propia solicitud corta y no depende de ningún archivo externo para funcionar.

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)

El texto se muestra fragmento a fragmento en cuanto se recibe, y la variable jetons_cumules solo se estabiliza en su valor final después del último message_delta, antes de que message_stop ponga fin al bucle. Una implementación que leyera este contador únicamente en message_stop encontraría ahí un evento sin campo usage. El fragmento también comprueba el tipo exacto del delta antes de leer su texto, puesto que un content_block_delta puede llevar un signature_delta en lugar de un text_delta cuando el modelo produce un bloque de razonamiento, un ajuste activo por defecto en Claude Sonnet 5.