> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime WebSocket

> WebSocket으로 실시간 음성 및 멀티모달 세션에 연결합니다

## 개요

이 엔드포인트는 실시간 음성 인식, 음성 합성, 음성 번역 또는 실시간 멀티모달 모델 세션에 사용합니다. 일반 `GET` 요청은 엔드포인트 메타데이터를 반환하고, WebSocket 업그레이드 요청은 라우팅된 상위 실시간 세션으로 프록시됩니다.

## 지원 범위

이 엔드포인트는 TokenLab의 실시간 WebSocket 프록시입니다. 같은 경로에서 일반 `GET /v1/realtime` 메타데이터 확인과 WebSocket 업그레이드를 지원합니다. `POST /v1/realtime/client_secrets`, `POST /v1/realtime/translations/client_secrets`, Realtime Calls(`accept`, `hangup`, `refer`, `reject`), legacy beta REST session / transcription-session 생성 같은 OpenAI Realtime REST 보조 엔드포인트는 제공하지 않습니다.

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

<Note>에이전트는 `/v1/models`에서 realtime 지원 모델을 확인한 뒤 socket을 열어야 합니다.</Note>

## 연결

<ParamField query="model" type="string" required>
  실시간 모델 ID입니다. 모델 세부정보에서 realtime을 지원하는 모델을 선택하세요.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer API 키입니다. WebSocket 클라이언트는 업그레이드 요청에 `Authorization: Bearer sk-your-api-key`를 보내야 합니다.
</ParamField>

<RequestExample>
  ```javascript JavaScript theme={null}
  import WebSocket from 'ws';

  const socket = new WebSocket('wss://api.tokenlab.sh/v1/realtime?model=gpt-realtime', {
    headers: { Authorization: 'Bearer sk-your-api-key' }
  });

  socket.on('open', () => {
    socket.send(JSON.stringify({
      type: 'session.update',
      session: { modalities: ['text', 'audio'] }
    }));
  });

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

  ```bash cURL theme={null}
  curl "https://api.tokenlab.sh/v1/realtime" \
    -H "Authorization: Bearer sk-your-api-key"
  ```
</RequestExample>

## 메시지

TokenLab은 클라이언트와 라우팅된 실시간 제공자 사이의 WebSocket 메시지를 전달합니다. 선택한 모델의 공식 이벤트 형식을 유지하고 `model`은 쿼리 문자열로 전달하세요.

## 과금 및 종료

실시간 세션은 같은 API 키 잔액을 사용합니다. TokenLab은 socket이 열릴 때 소액을 사전 차감하고 세션 종료 시 정산하거나 환불합니다.

세션이 끝나면 클라이언트 socket을 닫으세요. 상위 제공자가 먼저 닫으면 TokenLab은 가능한 경우 close code를 전달합니다.

## 응답 예시

<ResponseExample>
  ```json Connected theme={null}
  {
    "type": "session.created",
    "session": {
      "id": "sess_abc123",
      "model": "gpt-realtime",
      "modalities": ["text", "audio"]
    }
  }
  ```
</ResponseExample>

## 중요 필드

<ResponseField name="type" type="string">API가 반환하는 event 또는 message type입니다.</ResponseField>
<ResponseField name="session.id" type="string">실시간 제공자가 반환하는 식별자입니다. 지원 로그에 포함하기 위한 값이며 REST session URL이 아닙니다.</ResponseField>