Compatibilité avec l’API Realtime d’OpenAI

ElevenLabs Realtime utilise le même protocole de communication que l’API Realtime d’OpenAI : les mêmes événements client et serveur, via le même transport WebSocket. Si vous disposez déjà d’une application conçue avec le SDK Realtime d’OpenAI, vous pouvez la diriger vers ElevenLabs Realtime plutôt que vers api.openai.com, sans changer de SDK.

Modèles disponibles

Fonctionnement

1. Votre backend demande à ElevenLabs un secret client temporaire, associé à une configuration de session spécifique.
2. Votre frontend transmet ce secret client au SDK Realtime d’OpenAI à la place d’une clé API OpenAI.
3. Le SDK se connecte via WebSocket à ElevenLabs Realtime et la conversation se poursuit à l’aide des mêmes événements client et serveur que l’API Realtime d’OpenAI.

Générer un secret client

Demandez le secret client depuis votre backend, et non depuis le navigateur, afin que votre clé API ElevenLabs ne parvienne jamais au client.

Créez une clé API dans le Dashboard ici, que vous utiliserez pour accéder à l’API en toute sécurité.

Stockez la clé comme secret géré et transmettez-la aux SDK, soit sous forme de variable d’environnement via un fichier .env, soit directement dans la configuration de votre application, selon vos préférences.

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

La réponse contient value (l’identifiant éphémère utilisé par votre frontend), son heure d’expiration et la session négociée. Ne renvoyez que value au navigateur.

Connexion depuis le navigateur

Transmettez le secret client au SDK Realtime d’OpenAI (@openai/agents-realtime) comme clé API et dirigez le transport WebSocket vers le point de terminaison ElevenLabs plutôt que vers celui d’OpenAI par défaut.

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

Le SDK ne connecte automatiquement l’audio que pour son transport WebRTC. Via WebSocket, capturez et lisez vous-même l’audio PCM16 à 24 kHz, par exemple avec wavtools, l’utilitaire qu’OpenAI utilise également dans ses propres exemples WebSocket.

Limites

Ce guide couvre la connexion directe depuis un navigateur. La documentation pour les connexions depuis des SDK OpenAI Realtime côté serveur n’est pas encore publiée.

FAQ