> 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，只需将其指向 ElevenLabs Realtime，而非 `api.openai.com`。

> **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/zh/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`），并将 WebSocket 传输指向 ElevenLabs 端点，而非默认的 OpenAI 端点。

```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 时，请自行采集和播放 24 kHz 的 PCM16 音频，例如使用 [`wavtools`](https://www.npmjs.com/package/wavtools)。这也是 OpenAI 在自己的 WebSocket 示例中使用的辅助工具。

## 限制

本指南介绍如何直接从浏览器连接。暂未发布从服务器端 OpenAI Realtime SDK 连接的文档。

## 常见问题

#### 何时应使用 Realtime 模型？

Realtime 模型是为产品快速加入语音功能的最快方式。Eleven Realtime v1
mini 针对价格和速度优化；Eleven Realtime v1 max 针对质量和更复杂的
任务优化。

#### Realtime 模型采用什么底层架构？

Eleven Realtime v1 mini 和 max 使用级联架构，并进行了端到端优化，让每个
组件作为统一系统的一部分时都能发挥最佳效果。

#### 它们与在 ElevenAgents 中选择组件模型相比如何？

底层模型的具体信息未公开。每个组件均采用 ElevenLabs 最新研究成果，
并经过优化，以便在 Realtime 模型中协同发挥最佳效果。

#### Realtime 模型是融合模型吗？

不是。Realtime 模型采用级联架构：每个组件都是独立模型，基于
ElevenLabs 最新研究成果构建，并经过优化以实现最佳协同效果。