Streaming

Visão geralCopy Anchor Link

O streaming entrega a saída do modelo em pequenos eventos, em vez de aguardar a resposta completa. Use o streaming de Responses para um modelo que lista openai_responses em accepted_request_formats; mantenha o streaming de Chat Completions quando isso for o que seu SDK ou aplicação já espera.

Streaming de ResponsesCopy Anchor Link

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

O SSE de Responses mantém os nomes de eventos, ordem e campos documentados. Após a chegada do primeiro evento, um stream interrompido é considerado incompleto e não é reiniciado automaticamente.

WebSocket de ResponsesCopy Anchor Link

Conecte-se a wss://api.tokenlab.sh/v1/responses e envie eventos response.create. As respostas via WebSocket são sempre transmitidas via streaming e não suportam background ou response.cancel. Um response.create com generate: false retorna um ID que pode ser continuado sem gerar saída do modelo ou criar uma cobrança de modelo.

Cada conexão lida com uma resposta ativa por vez e dura até 60 minutos. Os eventos incluem um sequence_number com escopo de resposta. Eventos de stream chamados error usam um objeto de evento simples; falhas de conexão e de protocolo usam um objeto error aninhado.

Streaming de Chat CompletionsCopy Anchor Link

Se o seu framework ainda espera chunks SSE de /v1/chat/completions, isso também 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 do GeminiCopy Anchor Link

POST /v1beta/models/{model}:streamGenerateContent?alt=sse retorna chunks do Gemini. Um evento pode conter apenas metadados, eventos intermediários podem omitir finishReason, e o stream pode terminar naturalmente sem um marcador [DONE] de Chat Completions.

Condições de término do streamCopy Anchor Link

Condições típicas de conclusão:

• response.completed para streams da API de Responses
• finish_reason: "stop" para streams de Chat Completions
• finish_reason: "length" quando um limite de tokens é atingido
• eventos de chamada de ferramenta/função quando o modelo deseja usar ferramentas

Padrão de aplicação WebCopy Anchor Link

Execute o consumidor de stream do SDK no seu servidor. O navegador deve chamar seu próprio backend autenticado; mantenha a chave do TokenLab no ambiente do servidor. Encaminhe os deltas de texto para o navegador e cancele o stream upstream quando o usuário parar ou se desconectar. Use o SDK para analisar eventos SSE: um chunk de rede não é necessariamente um evento completo.

Lide bem com streamsCopy Anchor Link