Voice Live 2025-10-01 API-referentie

De Voice Live API biedt realtime, bidirectionele communicatie voor spraakgestuurde applicaties via WebSocket-verbindingen. Deze API ondersteunt geavanceerde functies zoals spraakherkenning, tekst-naar-spraak synthese, avatarstreaming, animatiedata en uitgebreide audioverwerkingsmogelijkheden.

De API gebruikt JSON-geformatteerde gebeurtenissen die via WebSocket-verbindingen worden verzonden om gesprekken, audiostreams, avatarinteracties en realtime antwoorden te beheren. Gebeurtenissen worden gecategoriseerd in clientgebeurtenissen (verzonden van client naar server) en serverevenementen (verzonden van server naar client).

Key Features

• Real-time audioverwerking: Ondersteuning voor meerdere audioformaten, waaronder PCM16 bij verschillende samplefrequenties en G.711-codecs
• Geavanceerde Spraakopties: OpenAI-stemmen, Azure aangepaste stemmen, Azure standaardstemmen en Azure persoonlijke stemmen
• Avatarintegratie: WebRTC-gebaseerde avatarstreaming met video, animatie en blendshapes
• Intelligent Turn Detection: Meerdere VAD-opties, waaronder Azure semantische VAD en server-side detectie
• Audioverbetering: Ingebouwde ruisonderdrukking en echo-onderdrukking
• Functieaanroep: Toolintegratie voor verbeterde conversatiemogelijkheden
• Flexibel sessiebeheer: Configureerbare uitvoermodaliteiten, instructies en responsparameters

Client Events

De Voice Live API ondersteunt de volgende clientgebeurtenissen die van de client naar de server kunnen worden gestuurd:

session.update

Werk de configuratie van de sessie bij. Dit event kan op elk moment worden verzonden om instellingen zoals spraak, uitvoermodaliteiten, beurtdetectie, tools en andere sessieparameters aan te passen. Let op dat zodra een sessie is geïnitialiseerd met een bepaald model, deze niet naar een ander model kan worden veranderd.

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

Voorbeeld met Azure Custom Voice

{
  "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

Stel een avatarverbinding tot stand door het SDP (Session Description Protocol) aanbod van de client voor WebRTC-mediaonderhandeling aan te bieden. Dit evenement is vereist bij het gebruik van avatarfuncties.

Event Structure

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

Properties

input_audio_buffer.append

Voeg audiobytes toe aan de input-audiobuffer.

Event Structure

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

Properties

input_audio_buffer.commit

Committen de input-audiobuffer voor verwerking.

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

Maak de input-audiobuffer leeg.

Event Structure

{
  "type": "input_audio_buffer.clear"
}

Properties

conversation.item.create

Voeg een nieuw item toe aan de context van het gesprek. Dit kan berichten, functieaanroepen en functieoproepantwoorden omvatten. Items kunnen op specifieke plekken in de gespreksgeschiedenis worden ingevoegd.

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

Voorbeeld met audio-inhoud

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

Voorbeeld met Function Call-uitvoer

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

Voorbeeld met MCP-goedkeuringsreactie

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

conversation.item.retrieve

Haal een specifiek item uit de gespreksgeschiedenis. Dit is nuttig voor het inspecteren van bewerkte audio na ruisonderdrukking en VAD.

Event Structure

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

Properties

conversation.item.truncate

Kort de audio-inhoud van een assistent-bericht in. Dit is handig om de weergave op een specifiek punt te stoppen en het begrip van de server te synchroniseren met de status van de client.

Event Structure

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

Properties

conversation.item.delete

Verwijder een item uit de gespreksgeschiedenis.

Event Structure

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

Properties

response.create

Geef de server opdracht een antwoord te maken via modelinferentie. Dit event kan responsspecifieke configuratie specificeren die de standaardinstellingen van sessies overschrijft.

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

Voorbeeld met Tool Choice

{
  "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
  }
}

Voorbeeld met animatie

{
  "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

Annuleer een lopende reactie. Dit stopt onmiddellijk de responsgeneratie en de bijbehorende audio-uitvoer.

Event Structure

{
  "type": "response.cancel"
}

Properties

input_audio_buffer.append

Het clientevent input_audio_buffer.append wordt gebruikt om audiobytes toe te voegen aan de input-audiobuffer. De audiobuffer is tijdelijke opslag waar je naartoe kunt schrijven en later kunt commiten.

In Server VAD (Voice Activity Detection)-modus wordt de audiobuffer gebruikt om spraak te detecteren en beslist de server wanneer hij commit. Wanneer server-VAD is uitgeschakeld, kan de client kiezen hoeveel audio hij in elk event plaatst tot maximaal 15 MiB. Bijvoorbeeld, het streamen van kleinere stukken vanuit de client kan ervoor zorgen dat de VAD responsiever wordt.

In tegenstelling tot de meeste andere client-events stuurt de server geen bevestigingsantwoord naar client-event input_audio_buffer.append .

Event structure

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

Properties

input_audio_buffer.clear

Het client-event input_audio_buffer.clear wordt gebruikt om de audiobytes in de buffer te wissen.

De server reageert met een input_audio_buffer.cleared gebeurtenis.

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

input_audio_buffer.commit

Het client-event input_audio_buffer.commit wordt gebruikt om de gebruikersinvoer-audiobuffer te commien, die een nieuw gebruikersbericht in het gesprek aanmaakt. Audio wordt getranscribeerd als input_audio_transcription het voor de sessie is geconfigureerd.

In server VAD-modus hoeft de client dit event niet te verzenden, de server commit automatisch de audiobuffer. Zonder server VAD moet de client de audiobuffer committen om een gebruikersberichtitem te maken. Dit client-event veroorzaakt een foutmelding als de input-audiobuffer leeg is.

Het committen van de input-audiobuffer genereert geen respons van het model.

De server reageert met een input_audio_buffer.committed gebeurtenis.

Event structure

{
  "type": "input_audio_buffer.commit"
}

Properties

Server Events

De Voice Live API stuurt de volgende servergebeurtenissen om status, antwoorden en data naar de client te communiceren:

session.created

Verzonden wanneer een nieuwe sessie succesvol is opgezet. Dit is het eerste event dat na het verbinden met de API wordt ontvangen.

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

Verzonden wanneer de sessieconfiguratie succesvol is bijgewerkt als reactie op een session.update clientgebeurtenis.

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

Geeft aan dat er een avatar WebRTC-verbinding wordt gelegd. Dit evenement wordt verzonden als reactie op een session.avatar.connect klantgebeurtenis.

Event Structure

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

Properties

conversation.item.created

Verzonden wanneer een nieuw item aan het gesprek wordt toegevoegd, hetzij via een klantgebeurtenis conversation.item.create , hetzij automatisch tijdens het genereren van reacties.

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

Voorbeeld met audio-item

{
  "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

Verzonden als reactie op een conversation.item.retrieve klantevenement, met het gevraagde gespreksonderwerp.

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

Het serverevent conversation.item.truncated wordt teruggegeven wanneer de client een eerder assistent-audiobericht afsnijdt met een conversation.item.truncate gebeurtenis. Dit event wordt gebruikt om het begrip van de server van de audio te synchroniseren met de weergave van de client.

Dit event kortte de audio af en verwijderde de server-side teksttranscriptie om te garanderen dat er geen tekst in de context is die de gebruiker niet kent.

Event structure

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

Properties

conversation.item.deleted

Verzonden als reactie op een conversation.item.delete klantgebeurtenis, waarin wordt bevestigd dat het opgegeven item uit het gesprek is verwijderd.

Event Structure

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

Properties

response.created

Verzonden wanneer een nieuwe responsgeneratie begint. Dit is het eerste evenement in een responsreeks.

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

Verzonden wanneer de responsgeneratie voltooid is. Dit evenement bevat de uiteindelijke reactie met alle uitvoeritems en gebruiksstatistieken.

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

Verzonden wanneer een nieuw uitvoeritem aan de respons wordt toegevoegd tijdens de generatie.

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

Verzonden wanneer een uitvoeritem voltooid is.

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

Het serverevent response.content_part.added wordt teruggegeven wanneer een nieuw inhoudsdeel wordt toegevoegd aan een assistent-berichtitem tijdens het genereren van reacties.

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

Het serverevent response.content_part.done wordt teruggegeven wanneer een contentonderdeel is gestreamd in een assistent-berichtitem.

Dit evenement wordt ook teruggegeven wanneer een reactie wordt onderbroken, onvolledig of geannuleerd.

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

Tekstinhoud streamen vanuit het model. Incrementeel verzonden terwijl het model tekst genereert.

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

Verstuurd wanneer de tekstgeneratie voltooid is.

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

Audio-inhoud van het model streamen. Audio wordt geleverd als base64-gecodeerde gegevens.

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

Verzonden wanneer de audio-inhoud is gegenereerd.

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

Streaming transcriptie van de gegenereerde audio-inhoud.

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

Verzonden wanneer het genereren van audiotranscripties voltooid is.

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

Het serverevent conversation.item.input_audio_transcription.completed is het resultaat van audio-transcriptie voor spraak die naar de audiobuffer is geschreven.

De transcriptie begint wanneer de input-audiobuffer door de client of server (in server_vad modus) wordt gecommitteerd. Transcriptie verloopt asynchroon met het creëren van reacties, dus dit event kan vóór of na de response events plaatsvinden.

Realtime API-modellen accepteren audio native, en dus is invoertranscriptie een apart proces dat wordt uitgevoerd op een apart spraakherkenningsmodel zoals whisper-1. Daardoor kan het transcript enigszins afwijken van de interpretatie van het model en moet het als een ruwe richtlijn worden behandeld.

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

Het serverevent conversation.item.input_audio_transcription.delta wordt teruggegeven wanneer invoer audiotranscriptie wordt geconfigureerd en er een transcriptieverzoek voor een gebruikersbericht in uitvoering is. Dit evenement levert gedeeltelijke transcriptieresultaten zodra deze beschikbaar zijn.

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

Het serverevent conversation.item.input_audio_transcription.failed wordt teruggegeven wanneer invoer-audiotranscriptie wordt geconfigureerd en een transcriptieverzoek voor een gebruikersbericht mislukte. Dit evenement staat los van andere error gebeurtenissen, zodat de klant het gerelateerde item kan identificeren.

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

Het serverevent response.animation_blendshapes.delta wordt teruggegeven wanneer het model animatie-blendshapes-data genereert als onderdeel van een respons. Dit event levert incrementele blendshapes-data zodra deze beschikbaar komt.

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

Het serverevent response.animation_blendshapes.done wordt teruggegeven wanneer het model klaar is met het genereren van animatie-blendshapes-gegevens als onderdeel van een respons.

Event structure

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

Properties

response.audio_timestamp.delta

Het serverevent response.audio_timestamp.delta wordt teruggegeven wanneer het model audio-timestampgegevens genereert als onderdeel van een reactie. Dit event levert incrementele tijdstempelgegevens voor uitlijning van audio en tekst zodra deze beschikbaar komt.

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

Verzonden wanneer de generatie van de audio-tijdstempel voltooid is.

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

Het serverevent response.animation_viseme.delta wordt teruggegeven wanneer het model animatie-visemegegevens genereert als onderdeel van een respons. Dit evenement levert incrementele viseme-gegevens zodra deze beschikbaar komen.

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

Het serverevent response.animation_viseme.done wordt teruggegeven wanneer het model is klaar met het genereren van animatievisemegegevens als onderdeel van een respons.

Event Structure

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

Properties

error

Het serverevent error wordt teruggegeven wanneer er een fout optreedt, wat een client- of serverprobleem kan zijn. De meeste fouten zijn herstelbaar en de sessie blijft open.

Event structure

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

Properties

Error properties

warning

Het serverevent warning wordt teruggegeven wanneer er een waarschuwing optreedt die de gespreksstroom niet onderbreekt. Waarschuwingen zijn informatief en de sessie verloopt normaal.

Event structure

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

Properties

Warning properties

input_audio_buffer.cleared

Het serverevent input_audio_buffer.cleared wordt teruggegeven wanneer de client de input-audiobuffer wist met een input_audio_buffer.clear gebeurtenis.

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

input_audio_buffer.committed

Het serverevent input_audio_buffer.committed wordt teruggegeven wanneer een input-audiobuffer wordt gecommit, hetzij door de client of automatisch in server VAD-modus. De item_id eigenschap is de ID van het aangemaakte gebruikersberichtitem. Zo wordt er ook een conversation.item.created gebeurtenis naar de cliënt gestuurd.

Event structure

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

Properties

input_audio_buffer.speech_started

Het serverevent input_audio_buffer.speech_started wordt teruggebracht in server_vad modus wanneer spraak wordt gedetecteerd in de audiobuffer. Dit gebeuren kan optreden telkens wanneer audio aan de buffer wordt toegevoegd (tenzij spraak al is gedetecteerd).

De cliënt moet verwachten een input_audio_buffer.speech_stopped gebeurtenis te ontvangen wanneer de spraak stopt. De item_id eigenschap is de ID van het gebruikersberichtitem dat wordt aangemaakt wanneer spraak stopt. Deze item_id wordt ook meegenomen in het input_audio_buffer.speech_stopped evenement, tenzij de client handmatig de audiobuffer commiteert tijdens de VAD-activatie.

Event structure

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

Properties

input_audio_buffer.speech_stopped

Het serverevent input_audio_buffer.speech_stopped wordt teruggebracht in server_vad modus wanneer de server het einde van spraak in de audiobuffer detecteert.

De server stuurt ook een conversation.item.created event met het gebruikersberichtitem dat is gemaakt vanuit de audiobuffer.

Event structure

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

Properties

rate_limits.updated

Het serverevent rate_limits.updated wordt aan het begin van een reactie geactiveerd om de bijgewerkte snelheidslimieten aan te geven.

Wanneer een antwoord wordt aangemaakt, worden sommige tokens gereserveerd voor de uitvoertokens. De hier getoonde tarieflimieten weerspiegelen die reservering, die vervolgens wordt aangepast zodra de reactie is afgerond.

Event structure

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

Properties

response.audio.delta

Het serverevent response.audio.delta wordt teruggegeven wanneer de door het model gegenereerde audio wordt bijgewerkt.

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

Het serverevent response.audio.done wordt teruggegeven wanneer de door het model gegenereerde audio is voltooid.

Dit evenement wordt ook teruggegeven wanneer een reactie wordt onderbroken, onvolledig of geannuleerd.

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

Het serverevent response.audio_transcript.delta wordt teruggegeven wanneer de door het model gegenereerde transcriptie van audio-uitvoer wordt bijgewerkt.

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

Het serverevent response.audio_transcript.done wordt teruggegeven wanneer de door het model gegenereerde transcriptie van audio-uitvoer is gestreamd.

Dit evenement wordt ook teruggegeven wanneer een reactie wordt onderbroken, onvolledig of geannuleerd.

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

Het serverevent response.function_call_arguments.delta wordt teruggegeven wanneer de door het model gegenereerde functie-aanroepargumenten worden bijgewerkt.

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

Het serverevent response.function_call_arguments.done wordt teruggegeven wanneer de door het model gegenereerde functie-aanroepargumenten klaar zijn met streamen.

Dit evenement wordt ook teruggegeven wanneer een reactie wordt onderbroken, onvolledig of geannuleerd.

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

Het serverevent mcp_list_tools.in_progress wordt teruggegeven wanneer de service begint met het vermelden van beschikbare tools van een mcp-server.

Event structure

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

Properties

mcp_list_tools.completed

Het serverevent mcp_list_tools.completed wordt geretourneerd wanneer de service de beschikbare tools van een MCP-server heeft voltooid.

Event structure

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

Properties

mcp_list_tools.failed

Het serverevent mcp_list_tools.failed wordt teruggegeven wanneer de service niet de beschikbare tools van een mcp-server vermeldt.

Event structure

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

Properties

response.mcp_call_arguments.delta

Het serverevent response.mcp_call_arguments.delta wordt teruggegeven wanneer de door het model gegenereerde MCP-tool-aanroepargumenten worden bijgewerkt.

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

Het serverevent response.mcp_call_arguments.done wordt teruggegeven wanneer de door het model gegenereerde mcp-tool-aanroepargumenten klaar zijn met streamen.

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

Het serverevent response.mcp_call.in_progress wordt teruggegeven wanneer een MCP-tool-aanroep begint te verwerken.

Event structure

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

Properties

response.mcp_call.completed

Het serverevent response.mcp_call.completed wordt teruggegeven wanneer een MCP-toolaanroep succesvol wordt voltooid.

Event structure

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

Properties

response.mcp_call.failed

Het serverevent response.mcp_call.failed wordt teruggegeven wanneer een MCP-toolaanroep faalt.

Event structure

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

Properties

response.output_item.added

Het serverevent response.output_item.added wordt teruggegeven wanneer een nieuw item wordt aangemaakt tijdens het genereren van reacties.

Event structure

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

Properties

response.output_item.done

Het serverevent response.output_item.done wordt teruggegeven wanneer een item klaar is met streamen.

Dit evenement wordt ook teruggegeven wanneer een reactie wordt onderbroken, onvolledig of geannuleerd.

Event structure

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

Properties

response.text.delta

Het serverevent response.text.delta wordt teruggegeven wanneer de door het model gegenereerde tekst wordt bijgewerkt. De tekst komt overeen met het text inhoudsgedeelte van een assistent-berichtitem.

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

Het serverevent response.text.done wordt teruggegeven wanneer de door het model gegenereerde tekst is gestreamd. De tekst komt overeen met het text inhoudsgedeelte van een assistent-berichtitem.

Dit evenement wordt ook teruggegeven wanneer een reactie wordt onderbroken, onvolledig of geannuleerd.

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

Basisaudioformaat dat wordt gebruikt voor invoeraudio.

Allowed Values:

• pcm16 - 16-bit PCM-audioformaat
• g711_ulaw - G.711 μ-law audioformaat
• g711_alaw - G.711 A-law audioformaat

RealtimeOutputAudioFormat

Audioformaat wordt gebruikt voor uitvoer van audio met specifieke samplefrequenties.

Allowed Values:

• pcm16 - 16-bit PCM audioformaat met standaard bemonsteringssnelheid (24kHz)
• pcm16_8000hz - 16-bit PCM-audioformaat met 8kHz samplefrequentie
• pcm16_16000hz - 16-bit PCM-audioformaat met een samplefrequentie van 16kHz
• g711_ulaw - G.711 μ-law (mu-law) audioformaat met 8kHz samplefrequentie
• g711_alaw - G.711 A-law audioformaat met 8kHz samplefrequentie

RealtimeAudioInputTranscriptionSettings

Configuratie voor input audio transcriptie.

RealtimeInputAudioNoiseReductionSettings

Dit kan zijn:

• Een RealtimeOpenAINoiseReduction-object
• Een RealtimeAzureDeepNoiseSuppression-object

RealtimeOpenAINoiseReduction

OpenAI ruisonderdrukkingsconfiguratie met expliciet typeveld, alleen beschikbaar voor gpt-realtime en gpt-realtime-mini modellen.

RealtimeAzureDeepNoiseSuppression

Configuratie voor input-audio ruisonderdrukking.

RealtimeInputAudioEchoCancellationSettings

Echo-onderdrukkingsconfiguratie voor server-side audioverwerking.

Voice Configuration

RealtimeVoice

Vereniging van alle ondersteunde spraakconfiguraties.

Dit kan zijn:

• Een RealtimeOpenAIVoice-object
• An RealtimeAzureVoice object

RealtimeOpenAIVoice

OpenAI spraakconfiguratie met expliciet type veld.

RealtimeAzureVoice

Base voor Azure voice-configuraties. Dit is een gediscrimineerde vakbond met verschillende typen:

RealtimeAzureStandardVoice

Azure standard voice configuration.

RealtimeAzureCustomVoice

Azure aangepaste spraakconfiguratie (voorkeur voor aangepaste stemmen).

Example:

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

RealtimeAzurePersonalVoice

Azure personal voice configuration.

Turn Detection

RealtimeTurnDetection

Configuratie voor bochtdetectie. Dit is een gediscrimineerde vakbond die meerdere VAD-typen ondersteunt.

RealtimeServerVAD

Basis VAD-gebaseerde beurtdetectie.

RealtimeOpenAISemanticVAD

OpenAI semantische VAD-configuratie die een model gebruikt om te bepalen wanneer de gebruiker is uitgesproken. Alleen beschikbaar voor gpt-realtime en gpt-realtime-mini modellen.

RealtimeAzureSemanticVAD

Azure semantische VAD, die bepaalt wanneer de gebruiker begint te spreken met behulp van een semantisch spraakmodel, wat robuustere detectie biedt in ruisachtige omgevingen.

RealtimeAzureSemanticVADMultilingual

Azure semantic VAD (default variant).

RealtimeEOUDetection

Azure End-of-Utterance (EOU) kon aangeven wanneer de eindgebruiker stopte met spreken, terwijl natuurlijke pauzes werden toegestaan. Detectie van eind-van-uiting kan voortijdige eind-van-bocht-richtingaanwijzers aanzienlijk verminderen zonder door de gebruiker waarneembare latentie toe te voegen.

Avatar Configuration

RealtimeAvatarConfig

Configuratie voor avatarstreaming en gedrag.

RealtimeIceServer

ICE-serverconfiguratie voor WebRTC-verbindingsonderhandeling.

RealtimeVideoParams

Videostreamingparameters voor avatar.

RealtimeVideoCrop

Video crop rechthoekdefinitie.

RealtimeVideoResolution

Videoresolutiespecificatie.

RealtimeAvatarScene

Configuratie voor het zoomniveau, positie, rotatie en bewegingsamplitude van de avatar in het videoframe.

Animation Configuration

RealtimeAnimation

Configuratie voor animatie-uitvoer, inclusief blendshapes en visemes.

RealtimeAnimationOutputType

Soorten animatiedata om uit te voeren.

Allowed Values:

• blendshapes - Gegevens over gezichtsblendshapes
• viseme_id - Viseme-identificatiegegevens

Session Configuration

RealtimeRequestSession

Sessieconfiguratieobject gebruikt in session.update gebeurtenissen.

RealtimeModality

Ondersteunde sessie-uitvoermodaliteiten.

Allowed Values:

• text - Tekstuitvoer
• audio - Audio-uitgang
• animation - Animatie-uitvoer
• avatar - Avatar video-uitgang

RealtimeAudioTimestampType

Uitvoertijdstempeltypes die worden ondersteund in audioresponsinhoud.

Allowed Values:

• word - Tijdstempels per woord in de uitvoeraudio

ReasoningEffort

Beperkt de inspanning van redeneren voor redeneermodellen. Bekijk de modeldocumentatie voor ondersteunde waarden voor elk model. Het verminderen van de redeneerinspanning kan leiden tot snellere antwoorden en minder tokens die worden gebruikt voor redeneren in een antwoord.

Allowed Values:

• none - Geen reden
• minimal - Minimale redeneerinspanning
• low - Lage redeneerinspanning - snellere antwoorden met minder redeneren
• medium - Medium redeneerinspanning - gebalanceerd tussen snelheid en redeneerdiepte
• high - Hoge redeneerinspanning - grondiger redeneren, kan langer duren
• xhigh - Extra hoge redeneerinspanning - maximale redeneerdiepte

Tool Configuration

We ondersteunen twee soorten tools: function calling en MCP-tools waarmee je verbinding maakt met een mcp-server.

RealtimeTool

Tooldefinitie voor functieaanroep.

RealtimeToolChoice

Strategie voor het selecteren van tools.

Dit kan zijn:

• "auto" - Laat het model kiezen
• "none" - Gebruik geen gereedschap
• "required" - Moet een gereedschap gebruiken
• { "type": "function", "name": "function_name" } - Gebruik specifieke functie

MCPTool

MCP-toolconfiguratie.

RealtimeConversationResponseItem

Dit is een unietype dat een van de volgende kan zijn:

RealtimeConversationUserMessageItem

Gebruikersbericht.

RealtimeConversationAssistantMessageItem

Assistent-bericht.

RealtimeConversationSystemMessageItem

Systeembericht.

RealtimeConversationFunctionCallItem

Functie-aanroepverzoekitem.

RealtimeConversationFunctionCallOutputItem

Functie-oproepresponsitem.

RealtimeConversationMCPListToolsItem

MCP lijst tools responsitem.

RealtimeConversationMCPCallItem

MCP oproeprespons-item.

RealtimeConversationMCPApprovalRequestItem

MCP-goedkeuringsverzoek.

RealtimeItemStatus

Status van gespreksonderwerpen.

Allowed Values:

• in_progress - Momenteel in behandeling
• completed - Succesvol voltooid
• incomplete - Onvolledig (onderbroken of mislukt)

RealtimeContentPart

Inhoudsdeel binnen een bericht.

RealtimeInputTextContentPart

Tekstinhoud.

RealtimeOutputTextContentPart

Tekstinhoud.

RealtimeInputAudioContentPart

Audio-inhoud.

RealtimeOutputAudioContentPart

Audio-inhoud.

Response Objects

RealtimeResponse

Responsobject dat een modelinferentierespons vertegenwoordigt.

RealtimeResponseStatus

Responsstatuswaarden.

Allowed Values:

• in_progress - Er wordt een reactie gegenereerd
• completed - Respons succesvol voltooid
• canceled - Reactie werd geannuleerd
• incomplete - Antwoord onvolledig (onderbroken)
• failed - Respons mislukt met fout

RealtimeUsage

Statistieken over tokengebruik.

TokenDetails

Gedetailleerde uitsplitsing van tokengebruik.

Error Handling

RealtimeErrorDetails

Foutinformatieobject.

RealtimeConversationRequestItem

Je gebruikt het RealtimeConversationRequestItem object om een nieuw item in het gesprek aan te maken via het conversation.item.create-evenement .

Dit is een unietype dat een van de volgende kan zijn:

RealtimeSystemMessageItem

Een systeembericht.

RealtimeUserMessageItem

Een gebruikersbericht.

RealtimeAssistantMessageItem

Een assistent-bericht.

RealtimeFunctionCallItem

Een functie-aanroepitem.

RealtimeFunctionCallOutputItem

Een functie die uitvoeritem aanroept.

RealtimeMCPApprovalResponseItem

Een MCP-goedkeuringsreactie.

RealtimeFunctionTool

De definitie van een functietool zoals gebruikt door het realtime eindpunt.

RealtimeItemStatus

Allowed Values:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

Het RealtimeResponseSession object vertegenwoordigt een sessie in de Realtime API. Het wordt gebruikt in sommige servergebeurtenissen, zoals:

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Related Resources

• Probeer de Voice Live quickstart
• Probeer de Voice Live agents quickstart
• Meer informatie over het gebruik van de Voice Live-API