스트리밍

개요

Streaming은 출력을 점진적으로 전달합니다. 모델이 네이티브 Responses 계약을 공개하고 동일 프로토콜 upstream 경로가 있을 때 Responses streaming을 사용하세요. 그 외에는 Chat Completions 또는 모델이 공개한 네이티브 프로토콜을 사용합니다.

권장: Responses Streaming

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

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

stream = client.responses.create(
    model="gpt-5.4",
    input="Write a short poem.",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const stream = await client.responses.create({
  model: 'gpt-5.4',
  input: 'Write a short poem.',
  stream: true
});

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}

Responses 및 Gemini streaming 경계

Responses SSE에서는 upstream 이벤트 이름, 순서, 필드를 보존하고 wire를 바꾸지 않은 채 usage와 종료 상태를 out-of-band로 읽습니다. 첫 이벤트 전달 후에는 다른 channel이나 credential을 시도하지 않습니다. Responses WebSocket은 공식 response.create 이벤트만 받습니다. stream은 암시적이며 이 transport에서는 background와 response.cancel을 제공하지 않습니다. background는 HTTP에서만 동작합니다. 연결은 직렬이며 multiplexing하지 않고 최대 60분입니다. Gemini SSE는 네이티브 chunk를 보존합니다. metadata-only 이벤트, finishReason 없는 중간 chunk, 자연스러운 EOF가 유효하며 Chat [DONE]을 추가하지 않습니다.

Chat Completions 스트리밍

프레임워크가 여전히 /v1/chat/completions의 SSE 청크를 기대하는 경우에도 동작합니다:

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write a short poem"}],
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

스트림 종료 조건

일반적인 완료 조건:

Responses API 스트림의 경우 response.completed
Chat Completions 스트림의 경우 finish_reason: "stop"
token 제한에 도달했을 때 finish_reason: "length"
모델이 도구를 사용하려고 할 때의 tool/function call 이벤트

웹 앱 패턴

async function streamChat(message) {
  const response = await fetch('https://api.tokenlab.sh/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk-your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4o',
      messages: [{ role: 'user', content: message }],
      stream: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split('\\n').filter(line => line.startsWith('data: '));

    for (const line of lines) {
      const data = line.slice(6);
      if (data === '[DONE]') return;
      const parsed = JSON.parse(data);
      const content = parsed.choices?.[0]?.delta?.content;
      if (content) {
        document.getElementById('output').textContent += content;
      }
    }
  }
}

모범 사례

새로운 구축에는 Responses streaming을 우선 사용

SDK 또는 앱이 이미 이를 지원한다면 /v1/responses를 사용하세요. 호환성이 중요한 통합에는 /v1/chat/completions 스트리밍을 유지하세요.

출력을 점진적으로 flush

전체 응답을 기다리기보다 delta 청크가 도착하는 대로 UI 또는 터미널에 추가하세요.

연결 끊김 및 재시도 처리

네트워크 끊김과 업스트림 연결 해제를 일반적인 실패 모드로 간주하고, 장시간 실행되는 세션에서는 신중하게 재연결하세요.

시작하기

핵심 가이드

미디어 가이드

개요

권장: Responses Streaming

Responses 및 Gemini streaming 경계

Chat Completions 스트리밍

스트림 종료 조건

웹 앱 패턴

모범 사례

​개요

​권장: Responses Streaming

​Responses 및 Gemini streaming 경계

​Chat Completions 스트리밍

​스트림 종료 조건

​웹 앱 패턴

​모범 사례

개요

권장: Responses Streaming

Responses 및 Gemini streaming 경계

Chat Completions 스트리밍

스트림 종료 조건

웹 앱 패턴

모범 사례