Streaming de Mensajes

Al crear un Mensaje, puedes establecer "stream": true para transmitir incrementalmente la respuesta usando eventos enviados por el servidor (SSE).

Streaming con SDKs

Nuestros SDKs de Python y TypeScript ofrecen múltiples formas de streaming. El SDK de Python permite tanto streams síncronos como asíncronos. Consulta la documentación en cada SDK para obtener detalles.

import anthropic

client = 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)

Tipos de eventos

Cada evento enviado por el servidor incluye un tipo de evento nombrado y datos JSON asociados. Cada evento usará un nombre de evento SSE (por ejemplo, event: message_stop), e incluirá el type de evento correspondiente en sus datos. Cada stream utiliza el siguiente flujo de eventos:

message_start: contiene un objeto Message con content vacío.
Una serie de bloques de contenido, cada uno de los cuales tiene un content_block_start, uno o más eventos content_block_delta, y un evento content_block_stop. Cada bloque de contenido tendrá un index que corresponde a su índice en el array content del Mensaje final.
Uno o más eventos message_delta, indicando cambios de nivel superior al objeto Message final.
Un evento final message_stop.

Los conteos de tokens mostrados en el campo usage del evento message_delta son acumulativos.

Eventos ping

Los streams de eventos también pueden incluir cualquier número de eventos ping.

Eventos de error

Ocasionalmente podemos enviar errores en el stream de eventos. Por ejemplo, durante períodos de alto uso, puedes recibir un overloaded_error, que normalmente correspondería a un HTTP 529 en un contexto no streaming:

Example error

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

Otros eventos

De acuerdo con nuestra política de versionado, podemos agregar nuevos tipos de eventos, y tu código debe manejar tipos de eventos desconocidos de manera elegante.

Tipos de delta de bloques de contenido

Cada evento content_block_delta contiene un delta de un tipo que actualiza el bloque de content en un index dado.

Delta de texto

Un delta de bloque de contenido text se ve así:

Text delta

event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}

Delta de JSON de entrada

Los deltas para bloques de contenido tool_use corresponden a actualizaciones para el campo input del bloque. Para soportar máxima granularidad, los deltas son cadenas JSON parciales, mientras que el tool_use.input final siempre es un objeto. Puedes acumular los deltas de cadena y analizar el JSON una vez que recibas un evento content_block_stop, usando una biblioteca como Pydantic para hacer análisis JSON parcial, o usando nuestros SDKs, que proporcionan ayudantes para acceder a valores incrementales analizados. Un delta de bloque de contenido tool_use se ve así:

Input JSON delta

event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

Nota: Nuestros modelos actuales solo soportan emitir una clave completa y propiedad de valor de input a la vez. Como tal, al usar herramientas, puede haber retrasos entre eventos de streaming mientras el modelo está trabajando. Una vez que una clave y valor de input se acumulan, los emitimos como múltiples eventos content_block_delta con json parcial fragmentado para que el formato pueda soportar automáticamente granularidad más fina en modelos futuros.

Delta de pensamiento

Al usar pensamiento extendido con streaming habilitado, recibirás contenido de pensamiento a través de eventos thinking_delta. Estos deltas corresponden al campo thinking de los bloques de contenido thinking. Para contenido de pensamiento, se envía un evento especial signature_delta justo antes del evento content_block_stop. Esta firma se usa para verificar la integridad del bloque de pensamiento. Un delta de pensamiento típico se ve así:

Thinking delta

event: content_block_delta
data: {"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"}}

El delta de firma se ve así:

Signature delta

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

Respuesta completa de Stream HTTP

Recomendamos encarecidamente que uses nuestros SDKs de cliente al usar el modo streaming. Sin embargo, si estás construyendo una integración API directa, necesitarás manejar estos eventos tú mismo. Una respuesta de stream está compuesta por:

Un evento message_start
Potencialmente múltiples bloques de contenido, cada uno de los cuales contiene:
- Un evento content_block_start
- Potencialmente múltiples eventos content_block_delta
- Un evento content_block_stop
Un evento message_delta
Un evento message_stop

También puede haber eventos ping dispersos a lo largo de la respuesta. Consulta Tipos de eventos para más detalles sobre el formato.

Solicitud básica de streaming

curl https://api.anthropic.com/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --data \
'{
  "model": "claude-opus-4-1-20250805",
  "messages": [{"role": "user", "content": "Hello"}],
  "max_tokens": 256,
  "stream": true
}'

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-1-20250805", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

Solicitud de streaming con uso de herramientas

El uso de herramientas ahora soporta streaming de granularidad fina para valores de parámetros como una característica beta. Para más detalles, consulta Streaming de herramientas de granularidad fina.

En esta solicitud, le pedimos a Claude que use una herramienta para decirnos el clima.

  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
    }'

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-opus-4-1-20250805","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Okay"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" let"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"'s"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" check"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" for"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Francisco"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" CA"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":":"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":", "}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"unit\": \"fah"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"renheit\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}

event: message_stop
data: {"type":"message_stop"}

Solicitud de streaming con pensamiento extendido

En esta solicitud, habilitamos el pensamiento extendido con streaming para ver el razonamiento paso a paso de Claude.

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": 20000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is 27 * 453?"
        }
    ]
}'

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-1-20250805", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"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"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n3. 27 * 400 = 10,800"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n4. 27 * 50 = 1,350"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n5. 27 * 3 = 81"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n6. 10,800 + 1,350 + 81 = 12,231"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

Solicitud de streaming con uso de herramienta de búsqueda web

En esta solicitud, le pedimos a Claude que busque en la web información actual del clima.

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_start
data: {"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_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"I'll check"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the current weather in New York City for you"}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"server_tool_use","id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","name":"web_search","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"query"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" NY"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"C to"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"day\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1 }

event: content_block_start
data: {"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_stop
data: {"type":"content_block_stop","index":2}

event: content_block_start
data: {"type":"content_block_start","index":3,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"Here's the current weather information for New York"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" City:\n\n# Weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" in New York City"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"\n\n"}}

...

event: content_block_stop
data: {"type":"content_block_stop","index":17}

event: message_delta
data: {"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_stop
data: {"type":"message_stop"}

Recuperación de errores

Cuando una solicitud de streaming se interrumpe debido a problemas de red, timeouts u otros errores, puedes recuperarte reanudando desde donde se interrumpió el stream. Este enfoque te ahorra tener que reprocesar toda la respuesta. La estrategia básica de recuperación involucra:

Capturar la respuesta parcial: Guarda todo el contenido que se recibió exitosamente antes de que ocurriera el error
Construir una solicitud de continuación: Crea una nueva solicitud API que incluya la respuesta parcial del asistente como el comienzo de un nuevo mensaje del asistente
Reanudar streaming: Continúa recibiendo el resto de la respuesta desde donde se interrumpió

Mejores prácticas para recuperación de errores

Usar características del SDK: Aprovecha las capacidades integradas de acumulación de mensajes y manejo de errores del SDK
Manejar tipos de contenido: Ten en cuenta que los mensajes pueden contener múltiples bloques de contenido (text, tool_use, thinking). Los bloques de uso de herramientas y pensamiento extendido no pueden ser parcialmente recuperados. Puedes reanudar el streaming desde el bloque de texto más reciente.

Primeros pasos

Modelos y precios

Aprende sobre Claude

Capacidades

Herramientas

Protocolo de Contexto del Modelo (MCP)

Casos de uso

Ingeniería de prompts

Probar y evaluar

Fortalecer las barreras de protección

Centro legal

Streaming de Mensajes

Streaming con SDKs

Tipos de eventos

Eventos ping

Eventos de error

Otros eventos

Tipos de delta de bloques de contenido

Delta de texto

Delta de JSON de entrada

Delta de pensamiento

Respuesta completa de Stream HTTP

Solicitud básica de streaming

Solicitud de streaming con uso de herramientas

Solicitud de streaming con pensamiento extendido

Solicitud de streaming con uso de herramienta de búsqueda web

Recuperación de errores

Mejores prácticas para recuperación de errores

Primeros pasos

Modelos y precios

Aprende sobre Claude

Capacidades

Herramientas

Protocolo de Contexto del Modelo (MCP)

Casos de uso

Ingeniería de prompts

Probar y evaluar

Fortalecer las barreras de protección

Centro legal

​Streaming con SDKs

​Tipos de eventos

​Eventos ping

​Eventos de error

​Otros eventos

​Tipos de delta de bloques de contenido

​Delta de texto

​Delta de JSON de entrada

​Delta de pensamiento

​Respuesta completa de Stream HTTP

​Solicitud básica de streaming

​Solicitud de streaming con uso de herramientas

​Solicitud de streaming con pensamiento extendido

​Solicitud de streaming con uso de herramienta de búsqueda web

​Recuperación de errores

​Mejores prácticas para recuperación de errores

Streaming con SDKs

Tipos de eventos

Eventos ping

Eventos de error

Otros eventos

Tipos de delta de bloques de contenido

Delta de texto

Delta de JSON de entrada

Delta de pensamiento

Respuesta completa de Stream HTTP

Solicitud básica de streaming

Solicitud de streaming con uso de herramientas

Solicitud de streaming con pensamiento extendido

Solicitud de streaming con uso de herramienta de búsqueda web

Recuperación de errores

Mejores prácticas para recuperación de errores