Compatibilità con l’API Realtime di OpenAI

Collega un client OpenAI Realtime esistente a ElevenLabs Realtime modificando l'endpoint e la configurazione della sessione.

ElevenLabs Realtime utilizza lo stesso protocollo wire dell’API Realtime di OpenAI: gli stessi eventi client e server, sullo stesso trasporto WebSocket. Se hai già un’app creata con l’SDK Realtime di OpenAI, puoi indirizzarla a ElevenLabs Realtime anziché a api.openai.com senza cambiare SDK.

Questa guida descrive il flusso basato sul browser, in cui un breve passaggio lato server genera una credenziale a breve durata e il browser si connette direttamente a ElevenLabs Realtime.

Modelli disponibili

Nome	Ottimizzato per
Eleven Realtime v1 mini	Prezzo e velocità
Eleven Realtime v1 max	Qualità e attività complesse

Come funziona

Il tuo backend richiede a ElevenLabs un client secret a breve durata, limitato a una configurazione di sessione specifica.
Il tuo frontend passa questo client secret all’SDK Realtime di OpenAI al posto di una chiave API di OpenAI.
L’SDK si connette tramite WebSocket a ElevenLabs Realtime e la conversazione prosegue usando gli stessi eventi client e server dell’API Realtime di OpenAI.

Genera un client secret

Richiedi il client secret dal tuo backend, non dal browser, così la tua chiave API di ElevenLabs non raggiunge mai il client.

Crea qui una chiave API nella dashboard, che userai per accedere all’API in modo sicuro.

Archivia la chiave come segreto gestito e passala agli SDK come variabile d’ambiente tramite un file .env oppure direttamente nella configurazione della tua app, in base alle tue preferenze.

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

La risposta contiene value (la credenziale temporanea che userà il tuo frontend), la sua scadenza e la session negoziata. Restituisci al browser solo value.

Una stringa model seleziona direttamente il comportamento dell’agente, anziché fare riferimento a un agent_id dal dashboard. La configurazione della sessione che invii quando generi il client secret è la sessione iniziale autorevole per quella credenziale.

Connetti dal browser

Passa il client secret all’SDK Realtime di OpenAI (@openai/agents-realtime) come chiave API e indirizza il trasporto WebSocket all’endpoint di ElevenLabs anziché a quello predefinito di 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 });

L’SDK collega automaticamente l’audio solo per il suo trasporto WebRTC. Tramite WebSocket, acquisisci e riproduci autonomamente l’audio PCM16 a 24 kHz, ad esempio con wavtools, lo stesso strumento di supporto che OpenAI usa nei propri esempi WebSocket.

Limitazioni

Questa guida descrive la connessione diretta da un browser. La documentazione per la connessione dagli SDK OpenAI Realtime lato server non è ancora pubblicata.

Domande frequenti

Quando dovrei usare i modelli Realtime?

I modelli Realtime sono il modo più veloce per iniziare a integrare la voce in un prodotto. Eleven Realtime v1 mini è ottimizzato per prezzo e velocità; Eleven Realtime v1 max è ottimizzato per la qualità e attività più complesse.

Qual è l'architettura alla base dei modelli Realtime?

Eleven Realtime v1 mini e max utilizzano un’architettura a cascata, ottimizzata end-to-end affinché ogni componente funzioni al meglio come parte di un unico sistema.

Come si confrontano con la selezione dei modelli dei componenti in ElevenAgents?

I dettagli dei modelli sottostanti non sono pubblici. Ogni componente utilizza le più recenti ricerche di ElevenLabs ed è ottimizzato per funzionare al meglio insieme agli altri nei modelli Realtime.

I modelli Realtime sono modelli fusi?

No. I modelli Realtime utilizzano un’architettura a cascata: ogni componente è un modello distinto, sviluppato con le più recenti ricerche di ElevenLabs e ottimizzato per funzionare al meglio insieme agli altri.