Compatibilidade com a API Realtime da OpenAI

Conecte um cliente OpenAI Realtime existente ao ElevenLabs Realtime alterando o endpoint e a configuração da sessão.

O ElevenLabs Realtime usa o mesmo protocolo de comunicação da API Realtime da OpenAI: os mesmos eventos de cliente e servidor, pelo mesmo transporte WebSocket. Se você já tem um app criado com o SDK Realtime da OpenAI, pode direcioná-lo ao ElevenLabs Realtime em vez de api.openai.com, sem trocar de SDK.

Este guia aborda o fluxo baseado no navegador, em que uma pequena etapa no servidor gera uma credencial de curta duração e o navegador se conecta diretamente ao ElevenLabs Realtime.

Modelos disponíveis

Nome	Otimizado para
Eleven Realtime v1 mini	Preço e velocidade
Eleven Realtime v1 max	Qualidade e tarefas complexas

Como funciona

Seu backend solicita à ElevenLabs um segredo de cliente de curta duração, limitado a uma configuração de sessão específica.
Seu frontend passa esse segredo de cliente ao SDK Realtime da OpenAI no lugar de uma chave de API da OpenAI.
O SDK se conecta por WebSocket ao ElevenLabs Realtime, e a conversa continua usando os mesmos eventos de cliente e servidor da API Realtime da OpenAI.

Gere um segredo de cliente

Solicite o segredo de cliente no backend, e não no navegador, para que sua chave de API da ElevenLabs nunca chegue ao cliente.

Crie uma chave de API no painel aqui, que você usará para acessar a API com segurança.

Armazene a chave como um segredo gerenciado e passe-a aos SDKs como uma variável de ambiente por meio de um arquivo .env ou diretamente na configuração do seu app, conforme preferir.

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

A resposta contém value (a credencial temporária que seu frontend usará), o prazo de expiração e a session negociada. Retorne apenas value ao navegador.

Uma string model seleciona diretamente o comportamento do agente, em vez de fazer referência a um agent_id do painel. A configuração de sessão enviada ao gerar o segredo de cliente é a sessão inicial autorizada para essa credencial.

Conecte-se pelo navegador

Passe o segredo de cliente ao SDK Realtime da OpenAI (@openai/agents-realtime) como chave de API e direcione o transporte WebSocket ao endpoint da ElevenLabs em vez do endpoint padrão da 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 });

O SDK conecta o áudio automaticamente apenas para seu transporte WebRTC. Por WebSocket, capture e reproduza você mesmo o áudio PCM16 a 24 kHz, por exemplo com wavtools, o mesmo auxiliar que a OpenAI usa em seus próprios exemplos de WebSocket.

Limitações

Este guia aborda a conexão direta por um navegador. A documentação para conexão usando SDKs Realtime da OpenAI no servidor ainda não foi publicada.

Perguntas frequentes

Quando devo usar os modelos Realtime?

Os modelos Realtime são a forma mais rápida de começar a incorporar voz a um produto. O Eleven Realtime v1 mini é otimizado para preço e velocidade; o Eleven Realtime v1 max é otimizado para qualidade e tarefas mais complexas.

Qual é a arquitetura por trás dos modelos Realtime?

O Eleven Realtime v1 mini e o max usam uma arquitetura em cascata, otimizada de ponta a ponta para que cada componente funcione melhor como parte de um único sistema.

Como eles se comparam à seleção dos modelos de componentes no ElevenAgents?

Os detalhes dos modelos subjacentes não são públicos. Cada componente usa as pesquisas mais recentes da ElevenLabs e é otimizado para funcionar melhor em conjunto nos modelos Realtime.

Os modelos Realtime são modelos integrados?

Não. Os modelos Realtime usam uma arquitetura em cascata: cada componente é um modelo distinto, criado com as pesquisas mais recentes da ElevenLabs e otimizado para funcionar melhor em conjunto.