Kompatibilität mit der OpenAI Realtime API

ElevenLabs Realtime verwendet dasselbe Wire-Protokoll wie OpenAIs Realtime API: dieselben Client- und Server-Ereignisse über denselben WebSocket-Transport. Wenn Sie bereits eine App mit OpenAIs Realtime SDK entwickelt haben, können Sie sie statt auf api.openai.com auf ElevenLabs Realtime verweisen, ohne das SDK zu wechseln.

Verfügbare Modelle

So funktioniert es

1. Ihr Backend fordert bei ElevenLabs ein kurzlebiges Client-Secret an, das auf eine bestimmte Sitzungskonfiguration begrenzt ist.
2. Ihr Frontend übergibt dieses Client-Secret anstelle eines OpenAI-API-Schlüssels an OpenAIs Realtime SDK.
3. Das SDK verbindet sich über WebSocket mit ElevenLabs Realtime, und die Unterhaltung läuft mit denselben Client- und Server-Ereignissen wie bei OpenAIs Realtime API ab.

Client-Secret erstellen

Fordern Sie das Client-Secret über Ihr Backend an, nicht über den Browser, damit Ihr ElevenLabs-API-Schlüssel nie den Client erreicht.

Erstellen Sie hier im Dashboard einen API-Schlüssel, den Sie verwenden, um sicher auf die API zuzugreifen.

Speichern Sie den Schlüssel als verwaltetes Secret und übergeben Sie ihn den SDKs je nach Präferenz entweder als Umgebungsvariable über eine .env-Datei oder direkt in der Konfiguration Ihrer App.

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),
    ),
)

Die Antwort enthält value (die kurzlebige Zugangsberechtigung, die Ihr Frontend verwendet), die Ablaufzeit und die ausgehandelte session. Geben Sie nur value an den Browser zurück.

Über den Browser verbinden

Übergeben Sie das Client-Secret als API-Schlüssel an OpenAIs Realtime SDK (@openai/agents-realtime) und verweisen Sie den WebSocket-Transport statt auf den standardmäßigen OpenAI-Endpoint auf den ElevenLabs-Endpoint.

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 });

Das SDK verbindet Audio nur für seinen WebRTC-Transport automatisch. Erfassen und spielen Sie über WebSocket PCM16-Audio mit 24 kHz selbst ab, zum Beispiel mit wavtools, demselben Hilfsprogramm, das OpenAI in seinen eigenen WebSocket-Beispielen verwendet.

Einschränkungen

Dieser Leitfaden behandelt die direkte Verbindung über einen Browser. Dokumentation für Verbindungen über serverseitige OpenAI-Realtime-SDKs ist noch nicht verfügbar.

FAQ