Zgodność z OpenAI Realtime API

ElevenLabs Realtime używa tego samego protokołu komunikacyjnego co Realtime API OpenAI: tych samych zdarzeń klienta i serwera, przez ten sam transport WebSocket. Jeśli masz już aplikację zbudowaną z użyciem Realtime SDK OpenAI, możesz skierować ją do ElevenLabs Realtime zamiast api.openai.com, bez zmiany SDK.

Dostępne modele

Jak to działa

1. Twój backend żąda od ElevenLabs krótkotrwałego sekretu klienta, ograniczonego do konkretnej konfiguracji sesji.
2. Twój frontend przekazuje ten sekret klienta do Realtime SDK OpenAI zamiast klucza API OpenAI.
3. SDK łączy się przez WebSocket z ElevenLabs Realtime, a rozmowa przebiega z użyciem tych samych zdarzeń klienta i serwera co Realtime API OpenAI.

Wygeneruj sekret klienta

Żądaj sekretu klienta z backendu, nie z przeglądarki, aby twój klucz API ElevenLabs nigdy nie trafił do klienta.

Utwórz klucz API w panelu tutaj, którego użyjesz, aby bezpiecznie uzyskać dostęp do API.

Przechowuj klucz jako zarządzany sekret i przekaż go do SDK jako zmienną środowiskową w pliku .env lub bezpośrednio w konfiguracji aplikacji — zależnie od preferencji.

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

Odpowiedź zawiera value (tymczasowe poświadczenie, którego użyje frontend), czas wygaśnięcia i uzgodnioną session. Zwróć do przeglądarki tylko value.

Połącz z przeglądarki

Przekaż sekret klienta do Realtime SDK OpenAI (@openai/agents-realtime) jako klucz API i skieruj transport WebSocket na endpoint ElevenLabs zamiast domyślnego endpointu 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 automatycznie obsługuje audio tylko w transporcie WebRTC. Przez WebSocket samodzielnie przechwytuj i odtwarzaj audio PCM16 z częstotliwością 24 kHz, na przykład za pomocą wavtools — tego samego narzędzia pomocniczego, którego OpenAI używa we własnych przykładach WebSocket.

Ograniczenia

Ten przewodnik dotyczy bezpośredniego łączenia z przeglądarki. Dokumentacja połączeń z serwerowych SDK OpenAI Realtime nie jest jeszcze dostępna.

FAQ