Streaming OpenAI API: recibe respuestas en tiempo real
Streaming OpenAI API permite recibir
la respuesta de un modelo progresivamente mientras
todavía se está generando. Mediante
Responses API y stream: true,
tu aplicación puede mostrar texto parcial,
reaccionar a eventos, procesar tool calls
y mejorar la experiencia del usuario sin esperar
a que finalice toda la respuesta.
¿Qué es Streaming OpenAI API?
Streaming OpenAI API es una modalidad en la que el servidor envía eventos parciales mientras el modelo continúa generando la respuesta. Esto permite mostrar texto progresivamente, detectar cuándo se añade contenido, recibir deltas y saber cuándo la respuesta quedó completamente finalizada.
Qué permite hacer Streaming OpenAI API
Streaming mejora la experiencia interactiva y permite reaccionar a la generación en tiempo real.
Mostrar texto parcial
Renderizar contenido a medida que llegan nuevos deltas.
Escuchar eventos
Reaccionar a eventos específicos del lifecycle de una respuesta.
Mejorar UX
Reducir la percepción de espera del usuario.
Streaming de tools
Algunas herramientas también emiten eventos incrementales.
Manejar errores
Detectar eventos de fallo o finalización incompleta.
Apps interactivas
Ideal para chat, asistentes y experiencias en tiempo real.
Cómo funciona Streaming en OpenAI API
La API mantiene una conexión y va enviando eventos parciales hasta completar la respuesta.
Activar streaming
Envías
stream: true
al crear
la respuesta.
Recibir eventos
El servidor envía deltas y cambios progresivos.
Detectar finalización
response.completed
indica que
la respuesta
terminó.
Activar Streaming OpenAI API con stream: true
Responses API admite una modalidad específica para devolver eventos progresivamente.
Convertir la respuesta en un flujo de eventos
Cuando utilizas
stream: true,
la API devuelve
eventos de streaming
en lugar
de esperar
a construir
el objeto final completo.
Streaming cambia cómo recibes la respuesta, no necesariamente la capacidad del modelo.
Ver Responses API →Ejemplo de Streaming OpenAI API en Python
Puedes iterar sobre los eventos y procesar únicamente los deltas de texto.
Mostrar texto mientras se genera
from openai import OpenAI
client = OpenAI()
stream = client.responses.create(
model="gpt-5.6-sol",
input="Explica qué es una API en términos simples.",
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
No todos
los eventos
contienen texto.
Conviene comprobar
siempre
event.type.
Eventos principales de Streaming OpenAI API
Responses API expone múltiples eventos que describen cómo evoluciona una respuesta.
| Evento | Función |
|---|---|
response.output_item.added |
Se añadió un nuevo elemento al output |
response.content_part.added |
Se añadió una nueva parte de contenido |
response.output_text.delta |
Se recibió un fragmento adicional de texto |
response.output_text.done |
El texto de esa parte quedó completo |
response.content_part.done |
Una parte de contenido quedó finalizada |
response.output_item.done |
Un elemento del output quedó completo |
response.completed |
La Response completa terminó correctamente |
Qué es response.output_text.delta
Este es uno de los eventos más importantes para interfaces de chat.
Fragmentos incrementales de texto
{
"type": "response.output_text.delta",
"delta": "Hola"
}Cada delta representa solo una parte del texto. Tu interfaz debe ir agregándolos al contenido existente.
response.output_text.done
Cuando termina una pieza de texto, la API emite un evento específico.
Texto final de la parte
response.output_text.done
puede incluir
el contenido final
correspondiente
a esa sección
de texto.
response.completed indica el final de la Response
Este evento representa la finalización completa de la respuesta.
La Response ya está terminada
En este punto puedes acceder al objeto Response final, incluyendo output, usage y demás información disponible.
Una parte de texto puede haber terminado mientras otras partes o tool calls siguen procesándose.
Streaming mediante Server-Sent Events
Responses API puede transmitir eventos incrementalmente mediante un flujo orientado a eventos.
Eventos enviados desde el servidor
En una integración HTTP, el cliente mantiene la conexión abierta mientras recibe eventos de streaming asociados a la Response.
Ejemplo de Streaming OpenAI API en JavaScript
El SDK también permite iterar sobre los eventos desde Node.js.
Procesar deltas de texto
import OpenAI from "openai";
const client = new OpenAI();
const stream = await client.responses.create({
model: "gpt-5.6-sol",
input: "Explica qué es machine learning.",
stream: true
});
for await (const event of stream) {
if (event.type === "response.output_text.delta") {
process.stdout.write(event.delta);
}
}Streaming con herramientas de OpenAI API
El flujo de eventos no está limitado al texto generado.
Las herramientas pueden tener sus propios eventos
Dependiendo de la herramienta, Responses API puede emitir eventos cuando una tool call comienza, cambia o finaliza.
Si tu agente utiliza tools, tu frontend puede mostrar estados como “buscando”, “analizando” o “ejecutando” mientras llegan eventos relacionados.
Streaming de comandos de Hosted Shell
La referencia actual incluye eventos específicos para shell.
| Evento | Función |
|---|---|
| Shell command added | Se añadió un comando a la tool call |
| Shell command delta | El comando recibió contenido incremental |
| Shell command done | El comando quedó completo |
| Shell output delta | Se recibe salida incremental del comando |
| Shell output done | La salida del comando finalizó |
Eventos de refusal en streaming
Las negativas del modelo también pueden aparecer progresivamente.
Refusal parcial y final
La referencia incluye eventos para texto de rechazo parcial y para la finalización del refusal.
Cómo manejar errores en Streaming OpenAI API
Una conexión de streaming puede terminar antes de obtener una respuesta completa.
Detecta eventos de error.
Controla desconexiones del cliente.
No asumas que recibir texto implica respuesta completa.
Espera un evento terminal cuando sea posible.
Guarda el Response ID si necesitas recuperación posterior.
stream_options en Responses API
Responses API dispone de opciones adicionales para streaming.
Configuración específica del flujo
La referencia actual
incluye opciones
como
include_obfuscation,
que controla
información adicional
incluida en eventos
de streaming.
stream_options
debe utilizarse
únicamente
cuando la respuesta
está configurada
para streaming.
Qué es include_obfuscation
OpenAI puede incluir contenido aleatorio en eventos para normalizar tamaños de payload.
Mitigación de ciertos side-channel attacks
La referencia indica que la obfuscation añade caracteres aleatorios a los eventos para normalizar el tamaño de los mensajes.
Si confías
en los enlaces
de red
y quieres optimizar
ancho de banda,
la referencia
permite establecer
include_obfuscation: false.
Reanudar eventos desde una Response almacenada
La operación de recuperación dispone actualmente de parámetros relacionados con streaming.
Continuar desde un sequence number
Al recuperar
una Response,
la referencia
permite utilizar
starting_after
para indicar
el número de secuencia
después del cual
debe comenzar
el stream.
Este tipo de mecanismo puede ayudar a diseñar interfaces capaces de continuar después de una interrupción.
Streaming vs respuesta normal
La diferencia principal es cuándo recibe contenido el usuario.
| Aspecto | Streaming | Respuesta normal |
|---|---|---|
| Entrega | Progresiva | Al finalizar |
| UX | Más interactiva | Espera inicial mayor |
| Implementación | Debe procesar eventos | Más sencilla |
| Chat | Muy adecuado | Adecuado para respuestas cortas |
Streaming vs Background Mode
Ambas opciones ayudan con tareas que no terminan instantáneamente, pero funcionan de manera distinta.
| Aspecto | Streaming | Background Mode |
|---|---|---|
| Conexión abierta | Sí | No necesita mantenerse |
| Output parcial | Sí | Normalmente consultas después |
| Uso | UX en tiempo real | Tareas largas |
| Cliente desconectado | Puede perder el stream | La tarea puede seguir |
Streaming OpenAI API vs Realtime API
Streaming y Realtime no son exactamente la misma tecnología.
| Aspecto | Responses Streaming | Realtime API |
|---|---|---|
| Objetivo | Transmitir una Response | Interacción bidireccional en tiempo real |
| Texto progresivo | Sí | Sí |
| Audio en vivo | No es su foco principal | Especialmente relevante |
| Conexión persistente | Durante la Response | Diseñada para sesiones persistentes |
| Uso típico | Chat de texto y agentes | Voz y experiencias en vivo |
Cómo usar Streaming en un chat
Una interfaz puede actualizar el mismo mensaje a medida que llegan nuevos deltas.
Crear un mensaje vacío del asistente.
Recibir
response.output_text.delta.
Añadir el delta al contenido visible.
Mantener el scroll cerca del final.
Marcar el mensaje como finalizado al recibir el evento terminal.
No expongas tu API key desde el navegador
El streaming hacia el frontend debe diseñarse sin exponer secretos de OpenAI.
Tu servidor mantiene la API key
El backend inicia el stream con OpenAI y retransmite únicamente los datos necesarios hacia el navegador del usuario.
Qué ocurre si el usuario cierra la página
Streaming depende de una conexión activa para recibir los eventos.
Diseña una estrategia de recuperación
Para procesos importantes, guarda identificadores y estados en el backend en lugar de depender exclusivamente de la sesión del navegador.
Si el trabajo debe continuar incluso cuando el cliente desaparece, evalúa Background Mode en lugar de depender únicamente del stream abierto.
Casos de uso de Streaming OpenAI API
Streaming aporta mayor valor cuando el usuario está esperando activamente una respuesta.
Chatbots: mostrar texto mientras se genera.
Asistentes: dar feedback inmediato al usuario.
Agentes: mostrar estados de herramientas durante el workflow.
Generación: visualizar artículos, análisis o código progresivamente.
Soporte: comenzar a responder antes de finalizar todo el contenido.
Cuándo conviene usar Streaming
Chat interactivo
El usuario está mirando la respuesta en pantalla.
Respuestas largas
Quieres comenzar a mostrar contenido rápidamente.
Tool workflows visibles
Quieres mostrar estados mientras el agente trabaja.
Cuándo no necesitas Streaming
Solo necesitas el JSON final
Procesar eventos puede añadir complejidad innecesaria.
Tarea muy larga
Si el usuario no necesita observar la generación, Background Mode puede ser mejor.
Miles de requests
Para procesamiento masivo offline, Batch API suele encajar mejor.
Streaming no reduce necesariamente el tiempo total
Su ventaja principal es reducir el tiempo percibido hasta que el usuario ve la primera parte de la respuesta.
Percepción frente a duración total
Aunque el modelo tarde un tiempo similar en terminar, el usuario puede empezar a leer mucho antes.
Cuánto cuesta Streaming OpenAI API
Streaming cambia la forma en la que recibes la respuesta, pero los costos principales siguen vinculados al modelo, tokens y herramientas utilizadas.
No es un tier de precio separado
Activar
stream: true
no debe confundirse
con Batch pricing
ni con otras
modalidades
de procesamiento.
Streaming y los límites de OpenAI API
Las solicitudes continúan sujetas a los límites del modelo y proyecto.
El stream no evita RPM o TPM
La modalidad de entrega no elimina los límites de solicitudes, tokens o capacidad aplicables.
Ver límites OpenAI API →Documentación oficial de Streaming OpenAI API
Los eventos disponibles pueden evolucionar conforme OpenAI amplía Responses API y sus herramientas.
Responses API streaming events
Revisa
stream,
eventos de texto,
tool events,
recuperación
y opciones
de streaming.
Guías relacionadas con Streaming OpenAI API
Continúa explorando Responses API, procesamiento y experiencias en tiempo real.
FAQ sobre Streaming OpenAI API
Respuestas sobre stream true, deltas, eventos, tools y Realtime API.
Streaming OpenAI API permite recibir eventos y fragmentos de una respuesta mientras el modelo todavía la está generando.
Utiliza
stream: true
al crear
la Response.
Es un evento que contiene una parte adicional del texto generado por el modelo.
Indica que la Response completa finalizó correctamente.
Sí. Responses API dispone de eventos específicos para varias tool calls y sus outputs.
No. Streaming mantiene una conexión para recibir eventos progresivos, mientras Background Mode permite que la tarea continúe sin mantener esa conexión abierta.
No. Streaming transmite una Response, mientras Realtime API está orientada a sesiones bidireccionales y de baja latencia.
No necesariamente. Su principal ventaja es permitir que el usuario vea contenido antes de que la respuesta esté completamente terminada.
La operación
de recuperación
de Responses API
dispone actualmente
de parámetros
como
starting_after
para comenzar
después de un
sequence number.
No. La API key debe mantenerse en tu backend. Tu servidor puede retransmitir los eventos necesarios al frontend.
Continúa con Realtime API de OpenAI
Ya sabes cómo transmitir una Response mientras se genera. El siguiente paso es aprender cómo construir sesiones interactivas de baja latencia con texto, audio y eventos bidireccionales.
Ver Realtime API →