OpenAI Realtime APIとの互換性

エンドポイントとセッション設定を変更して、既存のOpenAI RealtimeクライアントをElevenLabs Realtimeに接続します。

ElevenLabs Realtimeは、OpenAIのRealtime APIと同じワイヤープロトコルを使用します。つまり、同じWebSocketトランスポート上で、同じクライアントイベントとサーバーイベントを利用できます。すでにOpenAIのRealtime SDKで構築したアプリがある場合は、SDKを切り替えることなく、api.openai.comの代わりにElevenLabs Realtimeを指定できます。

このガイドでは、短期間有効な認証情報を小さなサーバーサイド処理で発行し、ブラウザがElevenLabs Realtimeに直接接続する、ブラウザベースのフローを説明します。

利用可能なモデル

名前	最適化対象
Eleven Realtime v1 mini	価格と速度
Eleven Realtime v1 max	品質と複雑なタスク

仕組み

バックエンドがElevenLabsに、特定のセッション設定にスコープされた短期間有効なクライアントシークレットをリクエストします。
フロントエンドが、OpenAI APIキーの代わりにそのクライアントシークレットをOpenAIのRealtime SDKへ渡します。
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）に渡し、デフォルトのOpenAIエンドポイントではなくElevenLabsのエンドポイントにWebSocketトランスポートを指定します。

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を使って、24kHzのPCM16オーディオを自分でキャプチャして再生してください。

制限事項

このガイドでは、ブラウザから直接接続する方法を説明しています。サーバーサイドの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の最新の研究成果をもとに構築され、最適に連携するように最適化されています。