핵심 가이드
스트리밍
모델 출력이 도착하는 대로 표시
개요
스트리밍은 전체 답변을 기다리는 대신 모델 출력을 작은 이벤트 단위로 전달합니다. accepted_request_formats에 openai_responses가 나열된 모델에는 Responses 스트리밍을 사용하고, SDK나 애플리케이션에서 이미 예상하고 있는 경우에는 Chat Completions 스트리밍을 유지하십시오.
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는 문서화된 이벤트 이름, 순서 및 필드를 유지합니다. 첫 번째 이벤트가 도착한 후 중단된 스트림은 불완전한 것으로 간주되며 자동으로 다시 시작되지 않습니다.
Responses WebSocket
wss://api.tokenlab.sh/v1/responses에 연결하여 response.create 이벤트를 전송하십시오. WebSocket 응답은 항상 스트리밍되며 background 또는 response.cancel을 지원하지 않습니다. generate: false를 포함한 response.create는 모델 출력을 생성하거나 모델 비용을 발생시키지 않고 계속할 수 있는 ID를 반환합니다.
각 연결은 한 번에 하나의 활성 응답을 처리하며 최대 60분 동안 지속됩니다. 이벤트에는 응답 범위의 sequence_number가 포함됩니다. error라는 이름의 스트림 이벤트는 플랫 이벤트 객체를 사용하며, 연결 및 프로토콜 오류는 중첩된 error 객체를 사용합니다.
Chat Completions 스트리밍
프레임워크에서 여전히 /v1/chat/completions로부터 SSE 청크를 예상하는 경우, 해당 방식도 작동합니다:
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}")Messages 스트리밍
"stream": true와 함께 POST /v1/messages를 호출하면 Anthropic Messages SSE 이벤트가 반환됩니다. message_stop 이벤트 이후에만 스트림이 완료된 것으로 처리하십시오. 더 일찍 종료되는 스트림은 불완전한 것입니다.
Gemini 스트리밍
POST /v1beta/models/{model}:streamGenerateContent?alt=sse는 Gemini 청크를 반환합니다. 이벤트에는 메타데이터만 포함될 수 있으며, 중간 이벤트는 finishReason을 생략할 수 있고, 스트림은 Chat Completions의 [DONE] 마커 없이 자연스럽게 종료될 수 있습니다.
스트림 종료 조건
일반적인 완료 조건:
- Responses API 스트림의 경우
response.completed - Messages 스트림의 경우
message_stop - Chat Completions 스트림의 경우
finish_reason: "stop" - 토큰 제한에 도달했을 때
finish_reason: "length" - 모델이 도구를 사용하려는 경우 도구/함수 호출 이벤트
웹 앱 패턴
서버에서 SDK 스트림 소비자를 실행하십시오. 브라우저는 인증된 자체 백엔드를 호출해야 하며, TokenLab 키는 서버 환경에 보관하십시오. 텍스트 델타를 브라우저로 전달하고 사용자가 중지하거나 연결을 끊을 때 업스트림 스트림을 취소하십시오. SSE 이벤트를 파싱하려면 SDK를 사용하십시오. 하나의 네트워크 청크가 반드시 하나의 완전한 이벤트인 것은 아닙니다.