TokenLab

오디오 및 실시간

Realtime WebSocket

WebSocket을 통해 실시간 음성 세션에 연결합니다

GET
/v1/realtime

개요

이 엔드포인트는 실시간 음성 세션에 사용합니다. 일반 GET 요청은 엔드포인트 메타데이터를 반환하며 API key가 필요하지 않습니다. ?model={model}을 포함한 WebSocket 업그레이드 요청은 선택한 모델과의 세션을 엽니다.

세부 정보에 realtime 작업이 나열된 모델만 세션을 열 수 있습니다. 연결하기 전에 GET /v1/models/{model}의 supported_operations를 확인하세요. 동일한 모델 세부 정보에 session.update 또는 response.create와 같이 세션이 허용하는 이벤트 및 필드가 나열되어 있습니다.

지원 범위

GET /v1/realtime은 WebSocket 하위 집합입니다. TokenLab은 선택한 모델의 실시간 이벤트를 중계합니다. 세션 생성, client_secrets, Calls 또는 레거시 베타 세션 API와 같은 OpenAI Realtime REST 헬퍼는 제공하지 않습니다.

수명이 긴 API key는 서버에 보관하세요. 이 엔드포인트는 브라우저나 모바일 앱을 위한 단기 client secret을 발급하지 않습니다.

실시간 세션은 API key 또는 Workspace의 전송 옵션을 사용합니다. X-TokenLab-Delivery-Policy 헤더나 쿼리 스트링으로 이를 재정의할 수 없습니다.

연결

modelstringquery필수

실시간 모델 ID입니다. WebSocket 업그레이드에 필수입니다.

Authorizationstringheader필수

업그레이드 요청과 함께 전송되는 Bearer sk-your-api-key입니다. x-api-key도 허용됩니다. 쿼리 스트링의 키는 허용되지 않습니다.

요청

import WebSocket from 'ws';

const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', 'grok-voice-latest');

const socket = new WebSocket(url, {
  headers: { Authorization: `Bearer ${process.env.TOKENLAB_API_KEY}` }
});

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

socket.on('message', (data) => {
  const event = JSON.parse(data.toString());
  if (event.type === 'error') {
    console.error('Realtime error', event.status, event.error.code);
    return;
  }
  console.log('realtime event', event.type);
});

socket.on('close', (code, reason) => console.log('closed', code, reason.toString()));

메시지

TokenLab은 클라이언트와 모델 간의 WebSocket 메시지를 중계합니다. 해당 모델의 이벤트 형식을 사용하고, 각 이벤트 내부가 아닌 쿼리 스트링에 model을 지정하세요. 메시지 크기는 최대 32 MiB입니다.

오류

소켓이 열리기 전에 사용할 수 있는 API key를 지정하지 않은 자격 증명은 HTTP 401, 403, 429 또는 503과 JSON 오류 본문과 함께 거부됩니다.

소켓이 열린 후 거부된 세션은 하나의 JSON 메시지를 보낸 다음 소켓을 닫습니다.

{
  "type": "error",
  "status": 400,
  "error": {
    "message": "model query parameter is required",
    "type": "invalid_request_error",
    "code": "missing_model"
  }
}
error.code원인
missing_modelmodel 쿼리 파라미터가 비어 있습니다
unsupported_operation해당 모델이 Realtime API용으로 게시되지 않았습니다
model_not_allowed, insufficient_balance, quota_exceeded키가 이 모델을 사용할 수 없거나, 잔액 또는 키 한도로 세션 예약을 충당할 수 없습니다. API 오류 처리를 참조하세요

이러한 거부의 경우 서비스는 코드 1008로 소켓을 닫습니다. 기타 종료 코드: 메시지가 너무 큰 경우 1009, 메시지 백로그가 쌓인 경우 1013, 서비스가 세션을 라우팅하거나 중계할 수 없는 경우 1011입니다. message가 아닌 code를 기준으로 오류를 처리하세요.

결제 및 종료

세션 비용은 API key 잔액에서 청구됩니다. TokenLab은 시작 시 예상 금액을 예약한 다음, 종료 시 실제 사용량을 정산하고 차액을 환불합니다. 모델 세부 정보에 표시된 대로 모델에 따라 토큰 또는 세션 시간 기준으로 청구됩니다.

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

응답 예시

아래 JSON은 일반 HTTP GET에 대한 응답입니다. 세션 이벤트가 아닙니다.

응답

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

주요 필드

objectstring
realtime.endpoint (HTTP GET 요청 시).
websocket_urlstring
/v1/realtime?model={model} (HTTP GET 요청 시).
protocolstring
tokenlab_realtime_proxy (HTTP GET 요청 시).

인증

BearerAuth
AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

쿼리 매개변수

model?string

실시간 모델 ID입니다. WebSocket 업그레이드 요청에는 필수이며, 일반 HTTP 메타데이터 확인에는 선택 사항입니다.

응답

application/json

application/json

application/json

application/json

application/json