Realtime WebSocket

개요Copy Anchor Link

이 엔드포인트는 스트리밍 음성 인식, 음성 합성, 음성 번역 또는 실시간 멀티모달 모델과 같은 실시간 세션에 사용합니다. 일반 GET 요청은 엔드포인트 메타데이터를 반환하며, WebSocket 업그레이드 요청은 선택한 모델의 실시간 세션을 시작합니다.

지원 범위Copy Anchor Link

TokenLab은 GET /v1/realtime에서 메타데이터 확인과 WebSocket 업그레이드에 사용할 수 있는 실시간 WebSocket 엔드포인트를 제공합니다. 이 엔드포인트는 WebSocket 하위 집합(WebSocket subset)으로 보아야 하며, 지원되는 realtime 모델 이벤트만 중계합니다. 세션 생성, client_secrets, Calls 통화 제어 API, legacy beta session API 같은 OpenAI Realtime REST 보조 표면은 지원하지 않습니다.

브라우저나 모바일 앱에서는 장기 API 키를 서버에 보관하세요. 이 엔드포인트는 단기 Realtime client secret을 발급하지 않습니다.

연결Copy Anchor Link

import WebSocket from 'ws';

const model = process.env.TOKENLAB_REALTIME_MODEL;
const apiKey = process.env.TOKENLAB_API_KEY;
if (!model || !apiKey) {
  throw new Error('Set TOKENLAB_REALTIME_MODEL and TOKENLAB_API_KEY');
}

const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', model);
const socket = new WebSocket(url, {
  headers: { Authorization: `Bearer ${apiKey}` }
});

socket.on('open', () => {
  console.log('Realtime connection open');
});

socket.on('message', (data) => {
  console.log('realtime event', data.toString());
});

socket.on('error', (error) => console.error(error.message));
socket.on('close', (code) => console.log('Realtime connection closed', code));

메시지Copy Anchor Link

TokenLab은 클라이언트와 선택한 실시간 모델 사이에서 WebSocket 메시지를 중계합니다. 해당 모델 문서에 명시된 이벤트 형식을 사용하고, model은 각 이벤트가 아니라 쿼리 문자열에 포함하세요.

과금 및 종료Copy Anchor Link

세션은 API 키 잔액으로 청구됩니다. TokenLab은 시작 시 예상 금액을 확보한 후, 종료 시 실제 사용량으로 정산하고 차액을 환불합니다.

세션이 끝나면 클라이언트 소켓을 닫으세요. 서비스가 먼저 세션을 닫는 경우, TokenLab은 가능한 경우 안전한 종료 이벤트/코드를 클라이언트에 전송합니다.

{
  "object": "realtime.endpoint",
  "websocket_url": "/v1/realtime?model={model}",
  "protocol": "tokenlab_realtime_proxy"
}

중요 필드Copy Anchor Link