Usare l'API GPT realtime tramite WebSocket

L'API Azure OpenAI GPT in tempo reale per la voce e l'audio fa parte della famiglia di modelli GPT-4o che supporta interazioni conversazionali a bassa latenza, "voce in ingresso, voce in uscita".

È possibile usare l'API Realtime tramite WebRTC, SIP o WebSocket per inviare input audio al modello e ricevere risposte audio in tempo reale.

Seguire le istruzioni in questo articolo per iniziare a usare l'API In tempo reale tramite WebSocket. Usare l'API Realtime tramite WebSocket negli scenari da server a server in cui la bassa latenza non è un requisito.

Usare la tabella seguente per scegliere il protocollo appropriato per lo scenario:

Prerequisiti

Prima di poter usare l'audio in tempo reale GPT, è necessario:

• Sottoscrizione Azure. Crearne uno gratuitamente.
• Una risorsa di Microsoft Foundry. Creare la risorsa in una delle aree supportate. Per la procedura di installazione, vedere Creare una risorsa Microsoft Foundry.
• Distribuzione di un modello GPT in tempo reale in un'area supportata, come descritto nella sezione relativa ai modelli supportati in questo articolo.
  • Nel portale foundry caricare il progetto. Selezionare Compila nel menu in alto a destra, quindi selezionare la scheda Modelli nel riquadro sinistro e selezionare Distribuisci un modello di base. Cercare il modello desiderato e selezionare Distribuisci nella pagina del modello.
• Librerie necessarie:
  • Python: pip install websockets azure-identity
  • JavaScript/Node.js: npm install ws @azure/identity

Modelli supportati

I modelli in tempo reale GPT sono disponibili per le distribuzioni globali nelle aree Stati Uniti orientali 2 e Svezia centrale.

• gpt-4o-mini-realtime-preview (2024-12-17)
• gpt-4o-realtime-preview (2024-12-17)
• gpt-realtime (2025-08-28)
• gpt-realtime-mini (2025-10-06)
• gpt-realtime-mini (2025-12-15)
• gpt-realtime-1.5 (2026-02-23)

Per altre informazioni sui modelli supportati, vedere la documentazione sui modelli e sulle versioni.

Connessione e autenticazione

L'API Realtime (tramite /realtime) è basata sull'API WebSocket per facilitare la comunicazione di streaming completamente asincrona tra l'utente finale e il modello.

L'API Realtime è accessibile tramite una connessione WebSocket sicura all'endpoint /realtime della risorsa OpenAI Azure.

È possibile costruire un URI di richiesta completo concatenando:

• Protocollo WebSocket (wss://) sicuro.
• Nome host dell'endpoint della risorsa Azure OpenAI, ad esempio my-aoai-resource.openai.azure.com
• Percorso API: openai/v1/realtime per disponibilità generale o openai/realtime per l'anteprima.
• Parametro della stringa di query model con il nome della distribuzione del modello gpt-realtime, gpt-realtime-1.5 o gpt-realtime-mini.
• (Solo versione di anteprima) Un parametro di stringa di query api-version per una versione dell'API supportata, come 2025-04-01-preview, e un parametro deployment invece di model.

L'esempio seguente è un URI di richiesta ben costruito /realtime :

wss://my-eastus2-openai-resource.openai.azure.com/openai/v1/realtime?model=gpt-realtime-deployment-name

wss://my-eastus2-openai-resource.openai.azure.com/openai/realtime?api-version=2025-04-01-preview&deployment=gpt-4o-mini-realtime-preview-deployment-name

Per eseguire l'autenticazione:

• Microsoft Entra (scelta consigliata): usare l'autenticazione basata su token con l'API /realtime per una risorsa OpenAI Azure con l'identità gestita abilitata. Applicare un token di autenticazione recuperato usando un Bearer token con l'intestazione Authorization .
• Chiave API: Un api-key oggetto può essere fornito in uno dei due modi seguenti:
  • Utilizzo di un'intestazione api-key per la connessione pre-handshake. Questa opzione non è disponibile in un ambiente browser.
  • Uso di un api-key parametro della stringa di query nell'URI della richiesta. I parametri della stringa di query vengono crittografati quando si usa HTTPS/WSS.

API in tempo reale tramite l'architettura webSocket

Una volta stabilita e autenticata la sessione di connessione WebSocket a /realtime , l'interazione funzionale avviene tramite eventi per l'invio e la ricezione di messaggi WebSocket. Questi eventi hanno la forma di un oggetto JSON.

Gli eventi possono essere inviati e ricevuti in parallelo e le applicazioni devono in genere gestirli in modo simultaneo e asincrono.

• Un chiamante lato client stabilisce una connessione a /realtime, che avvia un nuovo session.
• Un session oggetto crea automaticamente un oggetto predefinito conversation. Non è possibile supportare più conversazioni simultanee.
• conversation accumula i segnali di input fino all'avvio di response, tramite un evento diretto dal chiamante o automaticamente dal rilevamento di attività vocale.
• Ognuno response è costituito da uno o più items, che può incapsulare messaggi, chiamate di funzione e altre informazioni.
• Ogni messaggio item ha content_part, consentendo la rappresentazione di più modalità (testo e audio) in un singolo elemento.
• session gestisce la configurazione della gestione degli input del chiamante (ad esempio, l'audio dell'utente) e la gestione comune per la generazione di output.
• Ogni response.create avviato dal chiamante può eseguire l'override di alcuni dei comportamenti di output response, se desiderato.
• Gli elementi item creati dal server e gli elementi content_part nei messaggi possono essere popolati in modo asincrono e in parallelo. Ad esempio, la ricezione simultanea di informazioni su audio, testo e funzioni in modalità round robin.

Provare l'avvio rapido

Ora che sono stati eseguiti i passaggi precedenti, è possibile seguire le istruzioni nella guida introduttiva all'API Realtime per iniziare a usare l'API Realtime tramite WebSocket.

Contenuto correlato

• Provare l'avvio rapido per l'audio in tempo reale
• Vedere le informazioni di riferimento sulle API realtime
• Altre informazioni su Azure OpenAI quotas e limiti