Guías principales

Streaming

Muestra la salida del modelo a medida que llega

Información general

El streaming entrega la salida del modelo en pequeños eventos en lugar de esperar a la respuesta completa. Utilice el streaming de Responses para un modelo que enumere openai_responses en accepted_request_formats; mantenga el streaming de Chat Completions cuando eso sea lo que su SDK o aplicación ya espera.

Streaming de Responses

curl https://api.tokenlab.sh/v1/responses \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "Write a short poem.",
    "stream": true
  }'

Responses SSE mantiene los nombres de eventos, el orden y los campos documentados. Después de que llega el primer evento, un stream interrumpido se considera incompleto y no se reinicia automáticamente.

WebSocket de Responses

Conéctese a wss://api.tokenlab.sh/v1/responses y envíe eventos response.create. Las respuestas de WebSocket siempre se transmiten mediante streaming y no admiten background ni response.cancel. Un response.create con generate: false devuelve un ID que puede continuarse sin generar salida del modelo ni crear un cargo por modelo.

Cada conexión maneja una respuesta activa a la vez y dura hasta 60 minutos. Los eventos incluyen un sequence_number con alcance de respuesta. Los eventos de stream llamados error utilizan un objeto de evento plano; los fallos de conexión y de protocolo utilizan un objeto error anidado.

Streaming de Chat Completions

Si su framework aún espera fragmentos SSE de /v1/chat/completions, eso también funciona:

import os
from openai import OpenAI

with OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
) as client:
    finish_reason = None
    with client.chat.completions.create(
        model="gpt-5.6-terra",
        messages=[{"role": "user", "content": "Write a short poem."}],
        stream=True,
        stream_options={"include_usage": True},
    ) as stream:
        for chunk in stream:
            if not chunk.choices:
                continue
            choice = chunk.choices[0]
            if choice.delta.content:
                print(choice.delta.content, end="", flush=True)
            if choice.finish_reason:
                finish_reason = choice.finish_reason
    if finish_reason != "stop":
        raise RuntimeError(f"Stream ended without a complete text answer: {finish_reason}")

Streaming de Messages

POST /v1/messages con "stream": true devuelve eventos SSE de Anthropic Messages. Considere el stream como completo solo después de un evento message_stop; un stream que termina antes está incompleto.

Streaming de Gemini

POST /v1beta/models/{model}:streamGenerateContent?alt=sse devuelve fragmentos de Gemini. Un evento puede contener solo metadatos, los eventos intermedios pueden omitir finishReason, y el stream puede terminar naturalmente sin un marcador [DONE] de Chat Completions.

Condiciones de finalización del stream

Condiciones de finalización típicas:

  • response.completed para streams de la API de Responses
  • message_stop para streams de Messages
  • finish_reason: "stop" para streams de Chat Completions
  • finish_reason: "length" cuando se alcanza un límite de tokens
  • eventos de llamada a herramientas/funciones cuando el modelo desea utilizar herramientas

Patrón de aplicación web

Ejecute el consumidor de stream del SDK en su servidor. El navegador debe llamar a su propio backend autenticado; mantenga la clave de TokenLab en el entorno del servidor. Reenvíe los deltas de texto al navegador y cancele el stream ascendente cuando el usuario se detenga o se desconecte. Utilice el SDK para analizar los eventos SSE: un fragmento de red no es necesariamente un evento completo.

Manejo correcto de los streams

En esta página