> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# OpenAI Realtime API 호환성

ElevenLabs Realtime은 OpenAI Realtime API와 동일한 와이어 프로토콜을 사용합니다. 즉, 동일한 WebSocket 전송 방식에서 동일한 클라이언트 및 서버 이벤트를 사용합니다. 이미 OpenAI Realtime SDK로 구축한 앱이 있다면 SDK를 바꾸지 않고 `api.openai.com` 대신 ElevenLabs Realtime을 사용하도록 설정할 수 있습니다.

> **Info**
>
> 이 가이드에서는 작은 서버 측 단계에서 단기 자격 증명을 발급하고 브라우저가 ElevenLabs Realtime에 직접 연결하는 브라우저 기반 흐름을 다룹니다.

## 사용 가능한 모델

| 이름                      | 최적화 대상      |
| ----------------------- | ----------- |
| Eleven Realtime v1 mini | 가격 및 속도     |
| Eleven Realtime v1 max  | 품질 및 복잡한 작업 |

## 작동 방식

1. 백엔드에서 특정 세션 구성으로 범위가 지정된 단기 클라이언트 시크릿을 ElevenLabs에 요청합니다.
2. 프런트엔드에서 OpenAI API 키 대신 OpenAI Realtime SDK에 해당 클라이언트 시크릿을 전달합니다.
3. SDK가 WebSocket을 통해 ElevenLabs Realtime에 연결하면 OpenAI Realtime API와 동일한 클라이언트 및 서버 이벤트를 사용해 대화가 진행됩니다.

## 클라이언트 시크릿 발급

ElevenLabs API 키가 클라이언트에 노출되지 않도록 브라우저가 아닌 백엔드에서 클라이언트 시크릿을 요청하세요.

[여기 대시보드에서 API 키를 생성하세요](https://elevenlabs.io/app/api/api-keys). 이 키는 API에 안전하게 [액세스](/docs/ko/api-reference/authentication)하는 데 사용됩니다.

키를 관리형 시크릿으로 저장하고, 선호에 따라 `.env` 파일을 통한 환경 변수 또는 앱 구성에서 직접 SDK에 전달하세요.

**`.env`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

```python
import os

from dotenv import load_dotenv
from elevenlabs import (
    CreateClientSecretRequest,
    ExpiresAfter,
    OpenAiAudioConfigInput,
    OpenAiAudioInputConfigInput,
    OpenAiAudioInputFormat,
    OpenAiAudioOutputConfigInput,
    OpenAiAudioOutputFormat,
    OpenAiSessionConfigInput,
    OpenAiTurnDetection,
)
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

client_secret = elevenlabs.conversational_ai.realtime.create_client_secret(
    request=CreateClientSecretRequest(
        session=OpenAiSessionConfigInput(
            type="realtime",
            model="eleven_realtime_v1_mini",
            instructions="You are a helpful, friendly voice assistant. Keep replies concise.",
            output_modalities=["audio"],
            audio=OpenAiAudioConfigInput(
                input=OpenAiAudioInputConfigInput(
                    format=OpenAiAudioInputFormat(type="audio/pcm", rate=24000),
                    turn_detection=OpenAiTurnDetection(type="semantic_vad", eagerness="medium"),
                ),
                output=OpenAiAudioOutputConfigInput(
                    format=OpenAiAudioOutputFormat(type="audio/pcm"),
                    voice="brian",
                ),
            ),
        ),
        expires_after=ExpiresAfter(anchor="created_at", seconds=600),
    ),
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

process.loadEnvFile();

const elevenlabs = new ElevenLabsClient();

const clientSecret = await elevenlabs.conversationalAi.realtime.createClientSecret({
  session: {
    type: "realtime",
    model: "eleven_realtime_v1_mini",
    instructions: "You are a helpful, friendly voice assistant. Keep replies concise.",
    outputModalities: ["audio"],
    audio: {
      input: {
        format: { type: "audio/pcm", rate: 24000 },
        turnDetection: { type: "semantic_vad", eagerness: "medium" },
      },
      output: {
        format: { type: "audio/pcm" },
        voice: "brian",
      },
    },
  },
  expiresAfter: { anchor: "created_at", seconds: 600 },
});
```

응답에는 `value`(프런트엔드에서 사용할 임시 자격 증명), 만료 시간, 협상된 `session`이 포함됩니다. 브라우저에는 `value`만 반환하세요.

> **Note**
>
> `model` 문자열은 대시보드의 `agent_id`를 참조하는 대신 에이전트의 동작을 직접 선택합니다. 클라이언트 시크릿을 발급할 때 전송하는 세션 구성은 해당 자격 증명의 권한 있는 초기 세션입니다.

## 브라우저에서 연결

클라이언트 시크릿을 API 키로 OpenAI Realtime SDK(`@openai/agents-realtime`)에 전달하고, 기본 OpenAI 엔드포인트 대신 ElevenLabs 엔드포인트를 사용하도록 WebSocket 전송 방식을 설정하세요.

```typescript
import { OpenAIRealtimeWebSocket, RealtimeAgent, RealtimeSession } from "@openai/agents-realtime";

const { value: clientSecret } = await fetch("/api/token").then((res) => res.json());

const agent = new RealtimeAgent({
  name: "ElevenLabs agent",
  instructions: "You are a helpful, friendly voice assistant. Keep replies concise.",
});

const transport = new OpenAIRealtimeWebSocket({
  url: "wss://api.elevenlabs.io/v1/convai/realtime",
});

const session = new RealtimeSession(agent, {
  transport,
  model: "eleven_realtime_v1_mini",
  config: {
    outputModalities: ["audio"],
    audio: { output: { voice: "brian" } },
  },
});

await session.connect({ apiKey: clientSecret });
```

SDK는 WebRTC 전송 방식에서만 오디오를 자동으로 연결합니다. WebSocket에서는 OpenAI가 자체 WebSocket 예시에서 사용하는 것과 동일한 헬퍼인 [`wavtools`](https://www.npmjs.com/package/wavtools)를 사용해 PCM16 오디오를 24kHz로 직접 캡처하고 재생하세요.

## 제한 사항

이 가이드에서는 브라우저에서 직접 연결하는 방법을 다룹니다. 서버 측 OpenAI Realtime SDK에서 연결하는 방법에 관한 문서는 아직 공개되지 않았습니다.

## FAQ

#### Realtime 모델은 언제 사용해야 하나요?

Realtime 모델은 제품에 음성을 구현하는 가장 빠른 방법입니다. Eleven Realtime v1
mini는 가격과 속도에 최적화되어 있으며, Eleven Realtime v1 max는 품질과 더
복잡한 작업에 최적화되어 있습니다.

#### Realtime 모델의 기반 아키텍처는 무엇인가요?

Eleven Realtime v1 mini 및 max는 캐스케이드 아키텍처를 사용하며, 각
구성 요소가 단일 시스템의 일부로서 가장 잘 작동하도록 엔드 투 엔드로 최적화되어 있습니다.

#### ElevenAgents에서 구성 요소 모델을 선택하는 것과 어떻게 비교되나요?

기반 모델의 세부 사항은 공개되지 않았습니다. 각 구성 요소는 ElevenLabs의 최신
연구를 활용하며 Realtime 모델 내에서 함께 가장 잘 작동하도록 최적화되어 있습니다.

#### Realtime 모델은 융합 모델인가요?

아닙니다. Realtime 모델은 캐스케이드 아키텍처를 사용합니다. 각 구성 요소는 별개의 모델이며,
ElevenLabs의 최신 연구를 바탕으로 함께 가장 잘 작동하도록 최적화되어 있습니다.