Streaming de API de IA: SSE y timeouts
Aprende eventos de Chat Completions y Responses, parsing SSE, primer resultado efectivo, timeouts por fase y diagnóstico de 499.
El streaming de una API de IA entrega eventos mientras el modelo genera, en vez de esperar al cuerpo completo. Mejora la percepción de respuesta, pero no reduce necesariamente la latencia del modelo y exige que el cliente interprete el protocolo correcto.
Chat Completions transmite fragmentos de completado; Responses usa eventos tipados. Un cliente puede recibir HTTP 200 y no mostrar nada si espera la forma equivocada.
Empieza sin buffering
curl -N -sS https://modelflare.dev/v1/responses \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_RESPONSES_MODEL","input":"Explain SSE.","stream":true}'
Prueba la misma petición con streaming desactivado para separar validación de parsing. Usa un ID real de Modelos y precios.
Trata SSE como un protocolo
Server-Sent Events contiene registros delimitados, no trozos arbitrarios de JSON. El cliente debe evitar buffering en HTTP, proxies y UI; reunir lecturas parciales; reconocer texto, razonamiento, herramientas, finalización y errores; conservar cancelación y uso final; y cerrar tras un evento terminal.
Mide fases distintas
| Medida | Significado |
|---|---|
| Conexión y autenticación | Llegada a la pasarela y validación de la clave |
| Cabeceras upstream | La ruta elegida empieza a responder |
| Primer resultado efectivo | Primer texto, razonamiento o herramienta útil |
| Primer texto visible | Primer contenido que ve la persona |
| Tiempo total | Finalización, fallo o cancelación |
Una llamada a herramienta puede ser efectiva antes de producir texto. Para operación conviene medir el primer resultado efectivo; para experiencia, también el primer texto visible.
Diseña timeouts por fase
Separa timeout de conexión, cabeceras o primer resultado, inactividad del stream y deadline global. Las tareas de razonamiento o herramientas pueden tardar más en mostrar texto. Ajusta los presupuestos con tráfico real, no con un único timeout corto.
Si el cliente, navegador o proxy cierra antes de terminar, Modelflare puede registrar 499. Indica una cancelación downstream, no demuestra por sí solo que el modelo o canal falló. Compara abortos, timeouts, primer resultado, modelo, grupo e instante de cancelación.
Si no aparece texto
- Repite con "stream": false.
- Confirma que el modelo admite el endpoint.
- Captura eventos crudos antes de la UI.
- Busca eventos de herramienta o razonamiento sin texto.
- Descarta buffering intermedio.
- Comprueba el evento terminal del parser.
- Revisa estado, tiempos y cancelación.
Si la petición normal funciona y llegan eventos, el problema suele estar en parsing o renderizado. Si no llega ningún evento, sigue la guía de errores. Para elegir formato, consulta Responses API frente a Chat Completions.