跳到导航
指南

OpenAI Realtime API 兼容性

只需更改端点和会话配置，即可将现有 OpenAI Realtime 客户端连接到 ElevenLabs Realtime。

ElevenLabs Realtime 使用与 OpenAI Realtime API 相同的通信协议：通过相同的 WebSocket 传输方式，使用相同的客户端和服务器事件。如果应用已基于 OpenAI Realtime SDK 构建，无需更换 SDK，只需将其指向 ElevenLabs Realtime，而非 api.openai.com。

本指南介绍基于浏览器的流程：服务器端执行一个简短步骤来生成短期有效的 凭证，然后浏览器直接连接到 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 密钥，用于安全地访问 API。

将密钥作为受管理的机密信息存储，并根据偏好，通过 .env 文件将其作为环境变量传递给 SDK，或直接写入应用配置。

.env
ELEVENLABS_API_KEY=<your_api_key_here>
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),
    ),
)

响应包含 value（前端将使用的临时凭证）、其过期时间以及协商后的 session。仅将 value 返回给浏览器。

model 字符串会直接选择智能体的行为，而不是引用控制台中的 agent_id。 生成客户端密钥时发送的会话配置，是该凭证的权威初始会话配置。

从浏览器连接

将客户端密钥作为 API 密钥传递给 OpenAI Realtime SDK（@openai/agents-realtime），并将 WebSocket 传输指向 ElevenLabs 端点，而非默认的 OpenAI 端点。

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。这也是 OpenAI 在自己的 WebSocket 示例中使用的辅助工具。

限制

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

常见问题

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

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

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

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