> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Compatibilidade com a API Realtime da OpenAI

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.

> **Info**
>
> 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

1. Seu backend solicita à ElevenLabs um segredo de cliente de curta duração, limitado a uma configuração de sessão específica.
2. Seu frontend passa esse segredo de cliente ao SDK Realtime da OpenAI no lugar de uma chave de API da OpenAI.
3. 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](https://elevenlabs.io/app/api/api-keys), que você usará para [acessar a API](/docs/pt/api-reference/authentication) 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`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

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

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

process.loadEnvFile();

const elevenlabs = new ElevenLabsClient();

const clientSecret = await elevenlabs.conversationalAi.realtime.createClientSecret({
  session: {
    type: "realtime",
    model: "eleven_realtime_v1_mini",
    instructions: "You are a helpful, friendly voice assistant. Keep replies concise.",
    outputModalities: ["audio"],
    audio: {
      input: {
        format: { type: "audio/pcm", rate: 24000 },
        turnDetection: { type: "semantic_vad", eagerness: "medium" },
      },
      output: {
        format: { type: "audio/pcm" },
        voice: "brian",
      },
    },
  },
  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.

> **Note**
>
> 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.

```typescript
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`](https://www.npmjs.com/package/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.