OpenAI Realtime API

Cos'è OpenAI Realtime API?

L'OpenAI Realtime API fornisce comunicazioni a bassa latenza tra la tua applicazione e i modelli che supportano nativamente interazioni speech-to-speech. Supporta anche input multimodali—audio, immagini e testo—e output multimodali—audio e testo—rendendolo ideale per esperienze vocali interattive.

Oltre agli agenti vocali, la Realtime API può essere usata per trascrizione audio in tempo reale trasmettendo audio tramite una connessione WebSocket. La documentazione evidenzia anche punti di partenza consigliati (come l'Agents SDK per TypeScript) per flussi di lavoro di agenti vocali basati su browser.

Caratteristiche Principali

• Interazioni speech-to-speech a bassa latenza: Progettata per esperienze audio conversazionali in tempo reale, non solo request/response.
• Input multimodali (audio, immagini, testo): Consente a una singola sessione di accettare diversi tipi di input in base al flusso dell'applicazione.
• Output multimodali (audio e testo): Supporta il ritorno di audio, testo o entrambi come parte dell'interazione.
• Metodi di connessione multipli: Scegli tra WebRTC (browser/lato client), WebSocket (lato server middle-tier con bassa latenza costante) e SIP (telefonia VoIP).
• Guide per sessioni e strumenti conversazionali: Include indicazioni su prompting, eventi del ciclo di vita della conversazione e gestione del comportamento della sessione sul server.
• Trascrizione realtime su WebSocket: Fornisce un percorso per trascrivere flussi audio in tempo reale.

Come Usare OpenAI Realtime API

1. Scegli un metodo di connessione in base a dove gira la tua app: WebRTC per uso browser/client, WebSocket per server/middle-tier o SIP per telefonia VoIP.
2. Inizia con una sessione. Per agenti vocali browser, i documenti consigliano l'Agents SDK per TypeScript, che usa WebRTC nel browser e WebSocket sul server.
3. Crea e inizializza una sessione nel tuo codice, poi connettiti usando una chiave API client (l'esempio usa RealtimeAgent e RealtimeSession con session.connect).
4. Interagisci con il modello usando eventi. Dopo la connessione, usa le guide fornite per prompting/steering, gestione del ciclo di vita della conversazione e (se necessario) controllo lato server tramite webhook.

La documentazione nota anche dettagli di migrazione GA (vedi FAQ) che influenzano l'autenticazione delle richieste Realtime.

Casi d'Uso

• Agente vocale browser-based con speech-to-speech: Usa WebRTC (spesso tramite Agents SDK per TypeScript) per connettere microfono e output audio per conversazioni interattive.
• Assistente realtime supportato da server: Usa una connessione WebSocket da un middle tier quando vuoi rete a bassa latenza costante e gestione centralizzata delle sessioni.
• Integrazione VoIP/telefonia: Connettiti via SIP quando il tuo deployment target è un ambiente telefonico anziché un browser web.
• Trascrizione audio in tempo reale: Trasmetti audio a un flusso di trascrizione Realtime su WebSocket per ricevere risultati di trascrizione mentre l'audio viene inviato.
• Interazione multimodale: Accetta audio insieme a immagini e testo in una singola sessione realtime, poi restituisci audio, testo o entrambi.

FAQ

Serve l'header beta con la GA Realtime API?

Per richieste GA, la documentazione indica che l'header OpenAI-Beta: realtime=v1 deve essere rimosso. Se vuoi mantenere il comportamento beta, continua a includerlo.

Come genero credenziali per sessioni Realtime lato client (browser)?

Nell'interfaccia GA, i documenti descrivono un singolo endpoint REST—POST /v1/realtime/client_secrets—per generare chiavi usate per inizializzare una connessione WebRTC o WebSocket dai client. L'esempio mostra la creazione di una configurazione sessione e il post a quell'endpoint.

In che modo WebRTC e WebSocket differiscono per dove girano?

La documentazione posiziona WebRTC come ideale per interazioni browser/lato client, mentre WebSocket è ideale per applicazioni lato server middle-tier con connessioni di rete a bassa latenza costante.

Quale cambiamento di URL si applica al recupero SDP WebRTC?

Quando inizializzi una sessione WebRTC nel browser, i documenti indicano che l'URL per ottenere informazioni sulla sessione remota via SDP è ora /v1/realtime/calls.

Posso usare la Realtime API per trascrizione senza comportamento completo da voice-agent?

Sì. La documentazione specifica esplicitamente la trascrizione audio realtime trascrivendo flussi audio in tempo reale su connessione WebSocket.

Alternative

• Usa l'Agents SDK per TypeScript senza costruire tutto direttamente sui primitivi Realtime: Questo ti mantiene focalizzato sull'orchestrazione degli agenti vocali, sfruttando comunque Realtime sotto il cofano per la connettività browser (WebRTC) e server (WebSocket).
• Costruisci un pipeline di trascrizione request/response invece di streaming: Se la tua app non richiede gestione audio in tempo reale, un flusso di trascrizione non realtime evita l'approccio session-based event-driven descritto per Realtime.
• Altri approcci di comunicazione realtime per voce: Se hai bisogno di flussi specifici per telefonia, l'integrazione basata su SIP è un'opzione tra i metodi di connessione Realtime; altrimenti, scegli tra WebRTC (browser) e WebSocket (server) a seconda del deployment.
• Chat multimodale con endpoint non realtime: Se i requisiti di latenza sono meno stringenti di una “comunicazione a bassa latenza”, un approccio di chat multimodale non realtime potrebbe adattarsi, anche se non seguirà lo stesso workflow di sessione streaming/event descritto nella documentazione Realtime.