Compatibilidad con la API Realtime de OpenAI

ElevenLabs Realtime utiliza el mismo protocolo de comunicación que la API Realtime de OpenAI: los mismos eventos de cliente y servidor, mediante el mismo transporte WebSocket. Si ya tienes una aplicación creada con el SDK Realtime de OpenAI, puedes dirigirla a ElevenLabs Realtime en lugar de a api.openai.com sin cambiar de SDK.

Modelos disponibles

Cómo funciona

1. Tu backend solicita a ElevenLabs un secreto de cliente de corta duración, limitado a una configuración de sesión específica.
2. Tu frontend pasa ese secreto de cliente al SDK Realtime de OpenAI en lugar de una clave de API de OpenAI.
3. El SDK se conecta mediante WebSocket a ElevenLabs Realtime y la conversación continúa usando los mismos eventos de cliente y servidor que la API Realtime de OpenAI.

Genera un secreto de cliente

Solicita el secreto de cliente desde tu backend, no desde el navegador, para que tu clave de API de ElevenLabs nunca llegue al cliente.

Crea una clave de API en el panel aquí, que usarás para acceder a la API de forma segura.

Guarda la clave como un secreto gestionado y pásala a los SDK como variable de entorno mediante un archivo .env o directamente en la configuración de tu app, según prefieras.

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 respuesta contiene value (la credencial efímera que usará tu frontend), su fecha de caducidad y la session negociada. Devuelve solo value al navegador.

Conéctate desde el navegador

Pasa el secreto de cliente al SDK Realtime de OpenAI (@openai/agents-realtime) como clave de API y dirige el transporte WebSocket a la ruta de API de ElevenLabs en lugar de a la predeterminada de 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 });

El SDK solo conecta el audio automáticamente para su transporte WebRTC. Con WebSocket, captura y reproduce tú mismo audio PCM16 a 24 kHz, por ejemplo con wavtools, el mismo asistente que OpenAI utiliza en sus propios ejemplos de WebSocket.

Limitaciones

Esta guía abarca la conexión directa desde un navegador. La documentación para conectarse desde SDKs Realtime de OpenAI del lado del servidor aún no está publicada.

Preguntas frecuentes