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));
curl "https://api.tokenlab.sh/v1/realtime" \
-H "Authorization: Bearer sk-your-api-key"
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}
오디오 및 실시간
Realtime WebSocket
WebSocket으로 실시간 음성 및 멀티모달 세션에 연결합니다
GET
/
v1
/
realtime
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));
curl "https://api.tokenlab.sh/v1/realtime" \
-H "Authorization: Bearer sk-your-api-key"
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}
개요
이 엔드포인트는 스트리밍 음성 인식, 음성 합성, 음성 번역 또는 실시간 멀티모달 모델과 같은 실시간 세션에 사용합니다. 일반GET 요청은 엔드포인트 메타데이터를 반환하며, WebSocket 업그레이드 요청은 선택한 모델의 실시간 세션을 시작합니다.
지원 범위
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을 발급하지 않습니다.
/v1/models에서 현재 실시간 모델을 선택하고 /v1/models/{model}을 확인한 뒤 TOKENLAB_REALTIME_MODEL을 설정하세요. 세션 이벤트와 설정은 모델에 따라 다릅니다. 아래 JSON 예시는 일반 HTTP GET 응답이며 WebSocket 세션 이벤트가 아닙니다.연결
string
필수
실시간 모델 ID입니다. 모델 세부정보에서 realtime을 지원하는 모델을 선택하세요.
string
필수
Bearer API 키입니다. WebSocket 클라이언트는 업그레이드 요청에
Authorization: Bearer sk-your-api-key를 보내야 합니다.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));
curl "https://api.tokenlab.sh/v1/realtime" \
-H "Authorization: Bearer sk-your-api-key"
메시지
TokenLab은 클라이언트와 선택한 실시간 모델 사이에서 WebSocket 메시지를 중계합니다. 해당 모델 문서에 명시된 이벤트 형식을 사용하고,model은 각 이벤트가 아니라 쿼리 문자열에 포함하세요.
과금 및 종료
세션은 API 키 잔액으로 청구됩니다. TokenLab은 시작 시 예상 금액을 확보한 후, 종료 시 실제 사용량으로 정산하고 차액을 환불합니다. 세션이 끝나면 클라이언트 소켓을 닫으세요. 서비스가 먼저 세션을 닫는 경우, TokenLab은 가능한 경우 안전한 종료 이벤트/코드를 클라이언트에 전송합니다.응답 예시
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}
중요 필드
string
일반 HTTP GET 응답의 객체 유형입니다. 값은 항상
realtime.endpoint입니다.string
일반 HTTP GET이 반환하는 WebSocket 연결의 상대 경로인
/v1/realtime?model={model}입니다. {model}을 선택한 모델의 ID로 바꾸세요.string
일반 HTTP GET이 반환하는 프로토콜 식별자입니다. 값은 항상
tokenlab_realtime_proxy입니다.string
API가 반환하는 event 또는 message type입니다.
string
realtime 연결을 통해 받은 불투명한 식별자입니다. 디버깅용 지원 로그에 포함하세요. REST session URL이 아닙니다.
인증
API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
쿼리 매개변수
Realtime model ID to route the WebSocket session. Required for WebSocket upgrade requests; optional for plain HTTP metadata checks.
응답
WebSocket connection established