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

# Compatibilità con l'API Realtime di OpenAI

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.

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

1. Il tuo backend richiede a ElevenLabs un client secret a breve durata, limitato a una configurazione di sessione specifica.
2. Il tuo frontend passa questo client secret all'SDK Realtime di OpenAI al posto di una chiave API di OpenAI.
3. 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](https://elevenlabs.io/app/api/api-keys), che userai per [accedere all'API](/docs/it/api-reference/authentication) 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`**

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

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

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

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

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