Informazioni di riferimento sulle API Live 2025-10-01 Voice

L'API Voice Live offre comunicazioni bidirezionali in tempo reale per le applicazioni abilitate per la voce usando connessioni WebSocket. Questa API supporta funzionalità avanzate, tra cui il riconoscimento vocale, la sintesi vocale, lo streaming avatar, i dati di animazione e le funzionalità complete di elaborazione audio.

L'API usa eventi in formato JSON inviati tramite connessioni WebSocket per gestire conversazioni, flussi audio, interazioni avatar e risposte in tempo reale. Gli eventi vengono classificati in eventi client (inviati da client a server) ed eventi server (inviati dal server al client).

Key Features

• Elaborazione audio in tempo reale: supporto per più formati audio, tra cui PCM16 a varie frequenze di campionamento e codec G.711
• Opzioni vocali avanzate: voci OpenAI, voci personalizzate di Azure, voci standard di Azure e voci personali di Azure
• Integrazione avatar: streaming di avatar basato su WebRTC con video, animazione e forme di fusione
• Rilevamento dei turni intelligenti: più opzioni VAD, tra cui vad semantico di Azure e rilevamento lato server
• Miglioramento audio: riduzione del rumore incorporata e annullamento dell'eco
• Chiamata di funzioni: integrazione degli strumenti per funzionalità di conversazione avanzate
• Gestione delle sessioni flessibili: modalità di output configurabili, istruzioni e parametri di risposta

Client Events

L'API Voice Live supporta gli eventi client seguenti che possono essere inviati dal client al server:

session.update

Aggiornare la configurazione della sessione. Questo evento può essere inviato in qualsiasi momento per modificare le impostazioni, ad esempio voce, modalità di output, rilevamento dei turni, strumenti e altri parametri di sessione. Si noti che una volta inizializzata una sessione con un modello specifico, non può essere modificata in un altro modello.

Event Structure

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Properties

Esempio con Voce personalizzata di Azure

{
  "type": "session.update",
  "session": {
    "voice": {
      "type": "azure-custom",
      "name": "my-custom-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "temperature": 0.7,
      "style": "cheerful"
    },
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "avatar": {
      "character": "lisa",
      "customized": false,
      "video": {
        "resolution": {
          "width": 1920,
          "height": 1080
        },
        "bitrate": 2000000
      }
    }
  }
}

session.avatar.connect

Stabilire una connessione avatar fornendo l'offerta SDP (Session Description Protocol) del client per la negoziazione multimediale WebRTC. Questo evento è obbligatorio quando si usano le funzionalità avatar.

Event Structure

{
  "type": "session.avatar.connect",
  "client_sdp": "<client_sdp>"
}

Properties

input_audio_buffer.append

Aggiungere byte audio al buffer audio di input.

Event Structure

{
  "type": "input_audio_buffer.append",
  "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

Properties

input_audio_buffer.commit

Eseguire il commit del buffer audio di input per l'elaborazione.

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

Cancellare il buffer audio di input.

Event Structure

{
  "type": "input_audio_buffer.clear"
}

Properties

conversation.item.create

Aggiungere un nuovo elemento al contesto della conversazione. Ciò può includere messaggi, chiamate di funzione e risposte alle chiamate di funzione. Gli elementi possono essere inseriti in posizioni specifiche nella cronologia delle conversazioni.

Event Structure

{
  "type": "conversation.item.create",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Properties

Esempio con contenuto audio

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello there"
      }
    ]
  }
}

Esempio con output di Chiamata di funzione

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_123",
    "output": "{\"location\": \"San Francisco\", \"temperature\": \"70\"}"
  }
}

Esempio con la risposta di approvazione MCP

{
  "type": "conversation.item.create",
  "item": {
    "type": "mcp_approval_response",
    "approval_request_id": "mcp_approval_req_456",
    "approve": true,
  }
}

conversation.item.retrieve

Recuperare un elemento specifico dalla cronologia delle conversazioni. Ciò è utile per controllare l'audio elaborato dopo l'annullamento del rumore e il VAD.

Event Structure

{
  "type": "conversation.item.retrieve",
  "item_id": "item_ABC123"
}

Properties

conversation.item.truncate

Tronca il contenuto audio di un messaggio assistente. Ciò è utile per arrestare la riproduzione in un punto specifico e sincronizzare la comprensione del server con lo stato del client.

Event Structure

{
  "type": "conversation.item.truncate",
  "item_id": "item_ABC123",
  "content_index": 0,
  "audio_end_ms": 5000
}

Properties

conversation.item.delete

Rimuovere un elemento dalla cronologia delle conversazioni.

Event Structure

{
  "type": "conversation.item.delete",
  "item_id": "item_ABC123"
}

Properties

response.create

Indicare al server di creare una risposta tramite l'inferenza del modello. Questo evento può specificare una configurazione specifica della risposta che esegue l'override delle impostazioni predefinite della sessione.

Event Structure

{
  "type": "response.create",
  "response": {
    "modalities": ["text", "audio"],
    "instructions": "Be extra helpful and detailed.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "output_audio_format": "pcm16",
    "temperature": 0.7,
    "max_response_output_tokens": 1000
  }
}

Properties

Esempio con scelta degli strumenti

{
  "type": "response.create",
  "response": {
    "modalities": ["text"],
    "tools": [
      {
        "type": "function",
        "name": "get_current_time",
        "description": "Get the current time",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      }
    ],
    "tool_choice": "get_current_time",
    "temperature": 0.3
  }
}

Esempio con animazione

{
  "type": "response.create",
  "response": {
    "modalities": ["audio", "animation"],
    "animation": {
      "model_name": "default",
      "outputs": ["blendshapes", "viseme_id"]
    },
    "voice": {
      "type": "azure-custom",
      "name": "my-expressive-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "style": "excited"
    }
  }
}

response.cancel

Annullare una risposta in corso. Questa operazione arresta immediatamente la generazione della risposta e l'output audio correlato.

Event Structure

{
  "type": "response.cancel"
}

Properties

input_audio_buffer.append

L'evento client input_audio_buffer.append viene usato per aggiungere byte audio al buffer audio di input. Il buffer audio è un archivio temporaneo in cui è possibile scrivere e successivamente eseguire il commit.

In modalità VAD server (rilevamento attività vocali) il buffer audio viene usato per rilevare la voce e il server decide quando eseguire il commit. Quando il VAD del server è disabilitato, il client può scegliere la quantità di audio da inserire in ogni evento fino a un massimo di 15 MiB. Ad esempio, lo streaming di blocchi più piccoli dal client può consentire al VAD di essere più reattivo.

A differenza della maggior parte degli altri eventi client, il server non invia una risposta di conferma all'evento client input_audio_buffer.append.

Event structure

{
  "type": "input_audio_buffer.append",
  "audio": "<audio>"
}

Properties

input_audio_buffer.clear

L'evento client input_audio_buffer.clear viene usato per cancellare i byte audio nel buffer.

Il server risponde con un evento input_audio_buffer.cleared.

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

input_audio_buffer.commit

L'evento client input_audio_buffer.commit viene usato per eseguire il commit del buffer audio di input dell'utente, che crea un nuovo elemento del messaggio utente nella conversazione. L'audio viene trascritto se input_audio_transcription è configurato per la sessione.

Quando si usa la modalità VAD del server, il client non ha bisogno di inviare questo evento, il server esegue automaticamente il commit del buffer audio. Senza VAD server, il client deve eseguire il commit del buffer audio per creare un elemento di messaggio utente. Questo evento client genera un errore se il buffer audio di input è vuoto.

Il commit del buffer audio di input non crea una risposta dal modello.

Il server risponde con un evento input_audio_buffer.committed.

Event structure

{
  "type": "input_audio_buffer.commit"
}

Properties

Server Events

L'API Voice Live invia gli eventi del server seguenti per comunicare lo stato, le risposte e i dati al client:

session.created

Inviato quando viene stabilita una nuova sessione. Questo è il primo evento ricevuto dopo la connessione all'API.

Event Structure

{
  "type": "session.created",
  "session": {
    "id": "sess_ABC123DEF456",
    "object": "realtime.session",
    "model": "gpt-realtime",
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful assistant.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Properties

session.updated

Inviato quando la configurazione della sessione viene aggiornata correttamente in risposta a un session.update evento client.

Event Structure

{
  "type": "session.updated",
  "session": {
    "id": "sess_ABC123DEF456",
    "voice": {
      "type": "azure-custom",
      "name": "my-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012"
    },
    "temperature": 0.7,
    "avatar": {
      "character": "lisa",
      "customized": false
    }
  }
}

Properties

session.avatar.connecting

Indica che viene stabilita una connessione WebRTC avatar. Questo evento viene inviato in risposta a un session.avatar.connect evento client.

Event Structure

{
  "type": "session.avatar.connecting",
  "server_sdp": "<server_sdp>"
}

Properties

conversation.item.created

Inviato quando un nuovo elemento viene aggiunto alla conversazione, tramite un evento client conversation.item.create o automaticamente durante la generazione della risposta.

Event Structure

{
  "type": "conversation.item.created",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Properties

Esempio con elemento audio

{
  "type": "conversation.item.created",
  "item": {
    "id": "item_GHI789",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": null,
        "transcript": "What's the weather like today?"
      }
    ]
  }
}

conversation.item.retrieved

Inviato in risposta a un conversation.item.retrieve evento client, fornendo l'elemento di conversazione richiesto.

Event Structure

{
  "type": "conversation.item.retrieved",
  "item": {
    "id": "item_ABC123",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
      }
    ]
  }
}

Properties

conversation.item.truncated

L'evento server conversation.item.truncated viene restituito quando il client tronca un elemento di messaggio audio assistente precedente con un evento conversation.item.truncate. Questo evento viene usato per sincronizzare la comprensione dell'audio del server con la riproduzione del client.

Questo evento tronca l'audio e rimuove la trascrizione del testo sul lato server per assicurarsi che non ci sia testo nel contesto che l'utente non conosce.

Event structure

{
  "type": "conversation.item.truncated",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

Properties

conversation.item.deleted

Inviato in risposta a un conversation.item.delete evento client, confermando che l'elemento specificato è stato rimosso dalla conversazione.

Event Structure

{
  "type": "conversation.item.deleted",
  "item_id": "item_ABC123"
}

Properties

response.created

Inviato all'avvio di una nuova generazione di risposta. Questo è il primo evento in una sequenza di risposta.

Event Structure

{
  "type": "response.created",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "in_progress",
    "status_details": null,
    "output": [],
    "usage": {
      "total_tokens": 0,
      "input_tokens": 0,
      "output_tokens": 0
    }
  }
}

Properties

response.done

Inviato al termine della generazione della risposta. Questo evento contiene la risposta finale con tutti gli elementi di output e le statistiche di utilizzo.

Event Structure

{
  "type": "response.done",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "completed",
    "status_details": null,
    "output": [
      {
        "id": "item_DEF456",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
          }
        ]
      }
    ],
    "usage": {
      "total_tokens": 87,
      "input_tokens": 52,
      "output_tokens": 35,
      "input_token_details": {
        "cached_tokens": 0,
        "text_tokens": 45,
        "audio_tokens": 7
      },
      "output_token_details": {
        "text_tokens": 15,
        "audio_tokens": 20
      }
    }
  }
}

Properties

response.output_item.added

Inviato quando viene aggiunto un nuovo elemento di output alla risposta durante la generazione.

Event Structure

{
  "type": "response.output_item.added",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "assistant",
    "content": []
  }
}

Properties

response.output_item.done

Inviato al termine di un elemento di output.

Event Structure

{
  "type": "response.output_item.done",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm doing well, thank you for asking."
      }
    ]
  }
}

Properties

response.content_part.added

L'evento server response.content_part.added viene restituito quando viene aggiunta una nuova parte di contenuto a un elemento del messaggio di assistente durante la generazione della risposta.

Event Structure

{
  "type": "response.content_part.added",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": ""
  }
}

Properties

response.content_part.done

L'evento server response.content_part.done viene restituito quando una parte del contenuto viene eseguita in streaming in un elemento di messaggio assistente.

Questo evento viene restituito anche quando una risposta viene interrotta, incompleta o annullata.

Event Structure

{
  "type": "response.content_part.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": "Hello! I'm doing well, thank you for asking."
  }
}

Properties

response.text.delta

Streaming di contenuto di testo dal modello. Inviato in modo incrementale quando il modello genera testo.

Event Structure

{
  "type": "response.text.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm"
}

Properties

response.text.done

Inviato al termine della generazione del contenuto di testo.

Event Structure

{
  "type": "response.text.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Properties

response.audio.delta

Streaming di contenuti audio dal modello. L'audio viene fornito come dati con codifica Base64.

Event Structure

{
  "type": "response.audio.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

Properties

response.audio.done

Inviato al termine della generazione di contenuti audio.

Event Structure

{
  "type": "response.audio.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Properties

response.audio_transcript.delta

Trascrizione in streaming del contenuto audio generato.

Event Structure

{
  "type": "response.audio_transcript.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm doing"
}

Properties

response.audio_transcript.done

Inviato al termine della generazione della trascrizione audio.

Event Structure

{
  "type": "response.audio_transcript.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Properties

conversation.item.input_audio_transcription.completed

L'evento server conversation.item.input_audio_transcription.completed è il risultato della trascrizione audio per il parlato scritto nel buffer audio.

La trascrizione inizia quando viene eseguito il commit del buffer audio di input dal client o dal server (in modalità server_vad). La trascrizione viene eseguita in modo asincrono con la creazione della risposta, in modo che questo evento possa venire prima o dopo gli eventi di risposta.

I modelli API in tempo reale accettano l'audio in modo nativo e pertanto la trascrizione di input è un processo separato eseguito in un modello di riconoscimento vocale separato, ad whisper-1esempio . Pertanto, la trascrizione può divergere in qualche modo dall'interpretazione del modello e deve essere considerata una guida approssimativa.

Event structure

{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "<item_id>",
  "content_index": 0,
  "transcript": "<transcript>"
}

Properties

conversation.item.input_audio_transcription.delta

L'evento server conversation.item.input_audio_transcription.delta viene restituito quando viene configurata la trascrizione audio di input e viene in corso una richiesta di trascrizione per un messaggio utente. Questo evento fornisce risultati parziali di trascrizione non appena diventano disponibili.

Event structure

{
  "type": "conversation.item.input_audio_transcription.delta",
  "item_id": "<item_id>",
  "content_index": 0,
  "delta": "<delta>"
}

Properties

conversation.item.input_audio_transcription.failed

L'evento server conversation.item.input_audio_transcription.failed viene restituito quando è configurata la trascrizione audio di input e una richiesta di trascrizione per un messaggio utente non è riuscita. Questo evento è separato da altri eventi error in modo che il client possa identificare l'elemento correlato.

Event structure

{
  "type": "conversation.item.input_audio_transcription.failed",
  "item_id": "<item_id>",
  "content_index": 0,
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

Properties

Error properties

response.animation_blendshapes.delta

L'evento server response.animation_blendshapes.delta viene restituito quando il modello genera forme di animazione forma i dati come parte di una risposta. Questo evento fornisce dati incrementali di blendshapes man mano che diventano disponibili.

Event structure

{
  "type": "response.animation_blendshapes.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "frame_index": 0,
  "frames": [
    [0.0, 0.1, 0.2, ..., 1.0]
    ...
  ]
}

Properties

response.animation_blendshapes.done

L'evento server response.animation_blendshapes.done viene restituito quando il modello ha terminato di generare dati di forme di animazione come parte di una risposta.

Event structure

{
  "type": "response.animation_blendshapes.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
}

Properties

response.audio_timestamp.delta

L'evento server response.audio_timestamp.delta viene restituito quando il modello genera dati timestamp audio come parte di una risposta. Questo evento fornisce dati di timestamp incrementali per l'audio di output e l'allineamento del testo non appena diventa disponibile.

Event structure

{
  "type": "response.audio_timestamp.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "audio_duration_ms": 500,
  "text": "Hello",
  "timestamp_type": "word"
}

Properties

response.audio_timestamp.done

Inviato al termine della generazione del timestamp audio.

Event Structure

{
  "type": "response.audio_timestamp.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Properties

response.animation_viseme.delta

L'evento server response.animation_viseme.delta viene restituito quando il modello genera dati viseme di animazione come parte di una risposta. Questo evento fornisce dati viseme incrementali non appena diventano disponibili.

Event Structure

{
  "type": "response.animation_viseme.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "viseme_id": 1
}

Properties

response.animation_viseme.done

L'evento server response.animation_viseme.done viene restituito quando il modello ha terminato di generare dati viseme di animazione come parte di una risposta.

Event Structure

{
  "type": "response.animation_viseme.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Properties

error

L'evento server error viene restituito quando si verifica un errore, che potrebbe essere un problema del client o un problema del server. La maggior parte degli errori è recuperabile e la sessione rimane aperta.

Event structure

{
  "type": "error",
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>",
    "event_id": "<event_id>"
  }
}

Properties

Error properties

warning

L'evento server warning viene restituito quando si verifica un avviso che non interrompe il flusso di conversazione. Gli avvisi sono informativi e la sessione continua normalmente.

Event structure

{
  "type": "warning",
  "warning": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

Properties

Warning properties

input_audio_buffer.cleared

L'evento server input_audio_buffer.cleared viene restituito quando il client cancella il buffer audio di input con un evento input_audio_buffer.clear.

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

input_audio_buffer.committed

L'evento server input_audio_buffer.committed viene restituito quando viene eseguito il commit di un buffer audio di input, dal client o automaticamente in modalità VAD del server. La proprietà item_id è l'ID dell'elemento del messaggio utente creato. Un evento conversation.item.created viene quindi inviato anche al client.

Event structure

{
  "type": "input_audio_buffer.committed",
  "previous_item_id": "<previous_item_id>",
  "item_id": "<item_id>"
}

Properties

input_audio_buffer.speech_started

L'evento server input_audio_buffer.speech_started viene restituito in modalità server_vad quando viene rilevato il riconoscimento vocale nel buffer audio. Questo evento può verificarsi ogni volta che l'audio viene aggiunto al buffer (a meno che il riconoscimento vocale non sia già stato rilevato).

Il client dovrebbe aspettarsi di ricevere un evento input_audio_buffer.speech_stopped quando il riconoscimento vocale si arresta. La proprietà item_id è l'ID dell'elemento del messaggio utente creato all'arresto vocale. item_id viene incluso anche nell'evento input_audio_buffer.speech_stopped, a meno che il client non esegua manualmente il commit del buffer audio durante l'attivazione di VAD.

Event structure

{
  "type": "input_audio_buffer.speech_started",
  "audio_start_ms": 0,
  "item_id": "<item_id>"
}

Properties

input_audio_buffer.speech_stopped

L'evento server input_audio_buffer.speech_stopped viene restituito in modalità server_vad quando il server rileva la fine della voce nel buffer audio.

Il server invia anche un evento conversation.item.created con l'elemento del messaggio utente creato dal buffer audio.

Event structure

{
  "type": "input_audio_buffer.speech_stopped",
  "audio_end_ms": 0,
  "item_id": "<item_id>"
}

Properties

rate_limits.updated

L'evento server rate_limits.updated viene generato all'inizio di una risposta per indicare i limiti di frequenza aggiornati.

Quando viene creata una risposta, alcuni token sono riservati per i token di output. I limiti di velocità indicati di seguito riflettono la prenotazione, che viene quindi modificata di conseguenza al termine della risposta.

Event structure

{
  "type": "rate_limits.updated",
  "rate_limits": [
    {
      "name": "<name>",
      "limit": 0,
      "remaining": 0,
      "reset_seconds": 0
    }
  ]
}

Properties

response.audio.delta

L'evento server response.audio.delta viene restituito quando viene aggiornato l'audio generato dal modello.

Event structure

{
  "type": "response.audio.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Properties

response.audio.done

L'evento server response.audio.done viene restituito al termine dell'audio generato dal modello.

Questo evento viene restituito anche quando una risposta viene interrotta, incompleta o annullata.

Event structure

{
  "type": "response.audio.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

Properties

response.audio_transcript.delta

L'evento server response.audio_transcript.delta viene restituito quando viene aggiornata la trascrizione dell'output audio generata dal modello.

Event structure

{
  "type": "response.audio_transcript.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Properties

response.audio_transcript.done

L'evento server response.audio_transcript.done viene restituito quando viene eseguita la trascrizione dell'output audio generata dal modello.

Questo evento viene restituito anche quando una risposta viene interrotta, incompleta o annullata.

Event structure

{
  "type": "response.audio_transcript.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "transcript": "<transcript>"
}

Properties

response.function_call_arguments.delta

L'evento server response.function_call_arguments.delta viene restituito quando gli argomenti della chiamata di funzione generati dal modello vengono aggiornati.

Event structure

{
  "type": "response.function_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "delta": "<delta>"
}

Properties

response.function_call_arguments.done

L'evento server response.function_call_arguments.done viene restituito quando gli argomenti di chiamata di funzione generati dal modello vengono eseguiti in streaming.

Questo evento viene restituito anche quando una risposta viene interrotta, incompleta o annullata.

Event structure

{
  "type": "response.function_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "arguments": "<arguments>"
}

Properties

mcp_list_tools.in_progress

L'evento server mcp_list_tools.in_progress viene restituito quando il servizio inizia a elencare gli strumenti disponibili da un server mcp.

Event structure

{
  "type": "mcp_list_tools.in_progress",
  "item_id": "<mcp_list_tools_item_id>"
}

Properties

mcp_list_tools.completed

L'evento server mcp_list_tools.completed viene restituito quando il servizio completa l'elenco degli strumenti disponibili da un server mcp.

Event structure

{
  "type": "mcp_list_tools.completed",
  "item_id": "<mcp_list_tools_item_id>"
}

Properties

mcp_list_tools.failed

L'evento server mcp_list_tools.failed viene restituito quando il servizio non riesce ad elencare gli strumenti disponibili da un server mcp.

Event structure

{
  "type": "mcp_list_tools.failed",
  "item_id": "<mcp_list_tools_item_id>"
}

Properties

response.mcp_call_arguments.delta

L'evento server response.mcp_call_arguments.delta viene restituito quando vengono aggiornati gli argomenti di chiamata dello strumento mcp generati dal modello.

Event structure

{
  "type": "response.mcp_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "delta": "<delta>"
}

Properties

response.mcp_call_arguments.done

L'evento server response.mcp_call_arguments.done viene restituito quando gli argomenti di chiamata dello strumento mcp generati dal modello vengono eseguiti in streaming.

Event structure

{
  "type": "response.mcp_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "arguments": "<arguments>"
}

Properties

response.mcp_call.in_progress

L'evento server response.mcp_call.in_progress viene restituito quando una chiamata allo strumento MCP avvia l'elaborazione.

Event structure

{
  "type": "response.mcp_call.in_progress",
  "item_id": "<item_id>",
  "output_index": 0
}

Properties

response.mcp_call.completed

L'evento server response.mcp_call.completed viene restituito quando una chiamata allo strumento MCP viene completata correttamente.

Event structure

{
  "type": "response.mcp_call.completed",
  "item_id": "<item_id>",
  "output_index": 0
}

Properties

response.mcp_call.failed

L'evento server response.mcp_call.failed viene restituito quando una chiamata allo strumento MCP ha esito negativo.

Event structure

{
  "type": "response.mcp_call.failed",
  "item_id": "<item_id>",
  "output_index": 0
}

Properties

response.output_item.added

L'evento server response.output_item.added viene restituito quando viene creato un nuovo elemento durante la generazione della risposta.

Event structure

{
  "type": "response.output_item.added",
  "response_id": "<response_id>",
  "output_index": 0
}

Properties

response.output_item.done

L'evento server response.output_item.done viene restituito al termine del flusso di un elemento.

Questo evento viene restituito anche quando una risposta viene interrotta, incompleta o annullata.

Event structure

{
  "type": "response.output_item.done",
  "response_id": "<response_id>",
  "output_index": 0
}

Properties

response.text.delta

L'evento server response.text.delta viene restituito quando viene aggiornato il testo generato dal modello. Il testo corrisponde alla parte del contenuto text di un elemento del messaggio di assistente.

Event structure

{
  "type": "response.text.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Properties

response.text.done

L'evento server response.text.done viene restituito quando il testo generato dal modello viene eseguito in streaming. Il testo corrisponde alla parte del contenuto text di un elemento del messaggio di assistente.

Questo evento viene restituito anche quando una risposta viene interrotta, incompleta o annullata.

Event structure

{
  "type": "response.text.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "text": "<text>"
}

Properties

Components

Audio Formats

RealtimeAudioFormat

Formato audio di base usato per l'audio di input.

Allowed Values:

• pcm16 - Formato audio PCM a 16 bit
• g711_ulaw - Formato audio μ legge G.711
• g711_alaw - Formato audio legale G.711

RealtimeOutputAudioFormat

Formato audio usato per l'output audio con frequenze di campionamento specifiche.

Allowed Values:

• pcm16 - Formato audio PCM a 16 bit con frequenza di campionamento predefinita (24 kHz)
• pcm16_8000hz - Formato audio PCM a 16 bit con frequenza di campionamento a 8 kHz
• pcm16_16000hz - Formato audio PCM a 16 bit con frequenza di campionamento a 16 kHz
• g711_ulaw - Formato audio di legge μ G.711 (mu-law) con frequenza di campionamento a 8 kHz
• g711_alaw - Formato audio di legge G.711 con frequenza di campionamento a 8 kHz

RealtimeAudioInputTranscriptionSettings

Configurazione della trascrizione dell'audio di input.

RealtimeInputAudioNoiseReductionSettings

Può trattarsi di:

• Oggetto RealtimeOpenAINoiseReduction
• Oggetto RealtimeAzureDeepNoiseSuppression

RealtimeOpenAINoiseReduction

Configurazione della riduzione del rumore OpenAI con campo di tipo esplicito, disponibile solo per gpt-realtime i modelli e gpt-realtime-mini .

RealtimeAzureDeepNoiseSuppression

Configurazione per la riduzione del rumore audio di input.

RealtimeInputAudioEchoCancellationSettings

Configurazione dell'annullamento echo per l'elaborazione audio lato server.

Voice Configuration

RealtimeVoice

Unione di tutte le configurazioni vocali supportate.

Può trattarsi di:

• Oggetto RealtimeOpenAIVoice
• Oggetto RealtimeAzureVoice

RealtimeOpenAIVoice

Configurazione vocale OpenAI con campo di tipo esplicito.

RealtimeAzureVoice

Base per le configurazioni vocali di Azure. Si tratta di un'unione discriminante con tipi diversi:

RealtimeAzureStandardVoice

Configurazione vocale standard di Azure.

RealtimeAzureCustomVoice

Configurazione vocale personalizzata di Azure (preferita per le voci personalizzate).

Example:

{
  "type": "azure-custom",
  "name": "my-custom-voice",
  "endpoint_id": "12345678-1234-1234-1234-123456789012",
  "temperature": 0.7,
  "style": "cheerful",
  "locale": "en-US"
}

RealtimeAzurePersonalVoice

Configurazione vocale personale di Azure.

Turn Detection

RealtimeTurnDetection

Configurazione per il rilevamento dei turni. Si tratta di un'unione discriminante che supporta più tipi VAD.

RealtimeServerVAD

Rilevamento dei turni basato su VAD di base.

RealtimeOpenAISemanticVAD

Configurazione VAD semantica OpenAI che usa un modello per determinare quando l'utente ha terminato di parlare. Disponibile solo per gpt-realtime i modelli e gpt-realtime-mini .

RealtimeAzureSemanticVAD

VAD semantico di Azure, che determina quando l'utente inizia e parla usando un modello di riconoscimento vocale semantico, fornendo un rilevamento più affidabile in ambienti rumorosi.

RealtimeAzureSemanticVADMultilingual

VAD semantico di Azure (variante predefinita).

RealtimeEOUDetection

Azure End-of-Utterance (EOU) può indicare quando l'utente finale ha smesso di parlare consentendo pause naturali. Il rilevamento della fine delle espressioni può ridurre significativamente i segnali di fine turno prematuri senza aumentare la latenza percepibile dall'utente.

Avatar Configuration

RealtimeAvatarConfig

Configurazione per lo streaming e il comportamento dell'avatar.

RealtimeIceServer

Configurazione del server ICE per la negoziazione della connessione WebRTC.

RealtimeVideoParams

Parametri di streaming video per avatar.

RealtimeVideoCrop

Definizione del rettangolo di ritaglio video.

RealtimeVideoResolution

Specifica della risoluzione video.

RealtimeAvatarScene

Configurazione per il livello di zoom, la posizione, la rotazione e l'ampiezza di movimento dell'avatar nel fotogramma video.

Animation Configuration

RealtimeAnimation

Configurazione per gli output di animazione, incluse forme e visemi.

RealtimeAnimationOutputType

Tipi di dati di animazione da restituire.

Allowed Values:

• blendshapes - Forme facciali per la forma dei dati
• viseme_id - Dati dell'identificatore Viseme

Session Configuration

RealtimeRequestSession

Oggetto di configurazione sessione utilizzato negli session.update eventi.

RealtimeModality

Modalità di output della sessione supportate.

Allowed Values:

• text - Output di testo
• audio - Output audio
• animation - Output dell'animazione
• avatar - Output video avatar

RealtimeAudioTimestampType

Tipi di timestamp di output supportati nel contenuto della risposta audio.

Allowed Values:

• word - Timestamp per parola nell'audio di output

ReasoningEffort

Vincola il lavoro sul ragionamento per i modelli di ragionamento. Controllare la documentazione del modello per i valori supportati per ogni modello. La riduzione del lavoro di ragionamento può tradursi in risposte più veloci e in un minor numero di token usati per il ragionamento in una risposta.

Allowed Values:

• none - Nessun tentativo di ragionamento
• minimal - Minimo sforzo di ragionamento
• low - Scarso sforzo di ragionamento - risposte più veloci con meno ragionamenti
• medium - Sforzo di ragionamento medio - bilanciato tra velocità e profondità di ragionamento
• high - Sforzo di ragionamento elevato - ragionamento più approfondito, può richiedere più tempo
• xhigh - Sforzo di ragionamento più elevato - profondità massima di ragionamento

Tool Configuration

Sono supportati due tipi di strumenti: funzione chiamante e strumenti MCP che consentono di connettersi a un server mcp.

RealtimeTool

Definizione dello strumento per la chiamata di funzione.

RealtimeToolChoice

Strategia di selezione degli strumenti.

Può trattarsi di:

• "auto" - Consente al modello di scegliere
• "none" - Non usare gli strumenti
• "required" - Deve usare uno strumento
• { "type": "function", "name": "function_name" } - Usare una funzione specifica

MCPTool

Configurazione dello strumento MCP.

RealtimeConversationResponseItem

Si tratta di un tipo di unione che può essere uno dei seguenti:

RealtimeConversationUserMessageItem

Elemento del messaggio dell'utente.

RealtimeConversationAssistantMessageItem

Elemento del messaggio assistente.

RealtimeConversationSystemMessageItem

Elemento del messaggio di sistema.

RealtimeConversationFunctionCallItem

Elemento della richiesta di chiamata di funzione.

RealtimeConversationFunctionCallOutputItem

Elemento della risposta della chiamata di funzione.

RealtimeConversationMCPListToolsItem

Elemento di risposta degli strumenti elenco MCP.

RealtimeConversationMCPCallItem

Elemento di risposta della chiamata MCP.

RealtimeConversationMCPApprovalRequestItem

Elemento della richiesta di approvazione MCP.

RealtimeItemStatus

Stato degli elementi della conversazione.

Allowed Values:

• in_progress - Attualmente in fase di elaborazione
• completed -Completato
• incomplete - Incompleto (interrotto o non riuscito)

RealtimeContentPart

Parte contenuto all'interno di un messaggio.

RealtimeInputTextContentPart

Parte del contenuto del testo.

RealtimeOutputTextContentPart

Parte del contenuto del testo.

RealtimeInputAudioContentPart

Parte del contenuto audio.

RealtimeOutputAudioContentPart

Parte del contenuto audio.

Response Objects

RealtimeResponse

Oggetto risposta che rappresenta una risposta di inferenza del modello.

RealtimeResponseStatus

Valori dello stato della risposta.

Allowed Values:

• in_progress - La risposta viene generata
• completed - Risposta completata
• cancelled - Risposta annullata
• incomplete - Risposta incompleta (interrotta)
• failed - Risposta non riuscita con errore

RealtimeUsage

Statistiche di utilizzo dei token.

TokenDetails

Suddivisione dettagliata dell'utilizzo dei token.

Error Handling

RealtimeErrorDetails

Oggetto informazioni sull'errore.

RealtimeConversationRequestItem

Usare l'oggetto RealtimeConversationRequestItem per creare un nuovo elemento nella conversazione tramite l'evento conversation.item.create .

Si tratta di un tipo di unione che può essere uno dei seguenti:

RealtimeSystemMessageItem

Elemento del messaggio di sistema.

RealtimeUserMessageItem

Elemento del messaggio dell'utente.

RealtimeAssistantMessageItem

Elemento del messaggio dell'assistente.

RealtimeFunctionCallItem

Elemento di chiamata di funzione.

RealtimeFunctionCallOutputItem

Elemento di output di una chiamata di funzione.

RealtimeMCPApprovalResponseItem

Elemento di risposta di approvazione MCP.

RealtimeFunctionTool

Definizione di uno strumento di funzione usato dall'endpoint in tempo reale.

RealtimeItemStatus

Allowed Values:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

L'oggetto RealtimeResponseSession rappresenta una sessione nell'API Realtime. Viene usato in alcuni degli eventi del server, ad esempio:

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Related Resources

• Prova la Guida Introduttiva Voice Live
• Prova la guida introduttiva agli agenti Voice Live
• Altre informazioni su Come usare l'API Voice Live