Delen via

De Voice Live-API gebruiken

De Voice Live-API biedt een compatibele WebSocket-interface in vergelijking met de Azure OpenAI Realtime-API.

Tenzij anders vermeld, gebruikt de Voice Live-API dezelfde gebeurtenissen als de Azure OpenAI Realtime-API. Dit document bevat een verwijzing naar de eigenschappen van het gebeurtenisbericht die specifiek zijn voor de Voice Live-API.

Ondersteunde modellen en regio's

Zie het overzicht van de Voice Live-API voor een tabel met ondersteunde modellen en regio's.

Authentication

Een Microsoft Foundry-resource of een Azure Speech in Foundry Tools Services-resource is vereist voor het gebruik van de Voice Live-API.

Note

Het gebruik van Voice Live API is geoptimaliseerd voor Microsoft Foundry-resources. We raden u aan Om Microsoft Foundry-resources te gebruiken voor volledige beschikbaarheid van functies en de beste integratie-ervaring met Microsoft Foundry.
Azure Speech Services-resources bieden geen ondersteuning voor de integratie van Microsoft Foundry Agent Service en BYOM (Bring Your Own Model).

WebSocket-eindpunt

Het WebSocket-eindpunt voor de Voice Live-API is wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01 of, voor oudere resources, wss://<your-ai-foundry-resource-name>.cognitiveservices.azure.com/voice-live/realtime?api-version=2025-10-01. Het eindpunt is hetzelfde voor alle modellen. Het enige verschil is de vereiste model queryparameter of, wanneer u de Agent-service gebruikt, de agent_id en project_id parameters.

Een eindpunt voor een resource met een aangepast domein is bijvoorbeeld wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01&model=gpt-realtime

Credentials

De Voice Live-API ondersteunt twee verificatiemethoden:

  • Microsoft Entra (aanbevolen): Gebruik verificatie op basis van tokens voor een Microsoft Foundry-resource. Pas een opgehaald verificatietoken toe met behulp van een Bearer token met de Authorization header.
  • API-sleutel: een api-key kan op twee manieren worden opgegeven:
    • Gebruik een api-key verbindingskop op de prehandshake-verbinding. Deze optie is niet beschikbaar in een browseromgeving.
    • Gebruik een api-key queryreeksparameter op de aanvraag-URI. Queryreeksparameters worden versleuteld bij gebruik van https/wss.

Voor de aanbevolen sleutelloze verificatie met Microsoft Entra-id moet u het volgende doen:

  • Wijs de Cognitive Services User en Azure AI User rol toe aan uw gebruikersaccount of een beheerde identiteit. U kunt rollen toewijzen in Azure Portal onder Toegangsbeheer (IAM)>Roltoewijzing toevoegen.
  • Genereer een token met behulp van de Azure CLI of Azure SDK's. Het token moet worden gegenereerd met het https://ai.azure.com/.default bereik of het verouderde https://cognitiveservices.azure.com/.default bereik.
  • Gebruik het token in de Authorization header van de WebSocket-verbindingsaanvraag, met de indeling Bearer <token>.

Sessieconfiguratie

Vaak is de eerste gebeurtenis die door de aanroeper wordt verzonden op een zojuist tot stand gebrachte Voice Live API-sessie de session.update gebeurtenis. Met deze gebeurtenis wordt een brede set invoer- en uitvoergedrag bepaald, met eigenschappen voor het genereren van uitvoer en antwoorden en kan deze later worden overschreven met behulp van de response.create gebeurtenis.

Hier volgt een voorbeeldbericht session.update dat verschillende aspecten van de sessie configureert, waaronder draaidetectie, invoeraudioverwerking en spraakuitvoer. De meeste sessieparameters zijn optioneel en kunnen worden weggelaten als dat niet nodig is.

{
    "instructions": "You are a helpful AI assistant responding in natural, engaging language.",
    "turn_detection": {
        "type": "azure_semantic_vad",
        "threshold": 0.3,
        "prefix_padding_ms": 200,
        "silence_duration_ms": 200,
        "remove_filler_words": false,
        "end_of_utterance_detection": {
            "model": "semantic_detection_v1",
            "threshold_level": "default",
            "timeout_ms": 1000
        },
    },
    "input_audio_noise_reduction": {"type": "azure_deep_noise_suppression"},
    "input_audio_echo_cancellation": {"type": "server_echo_cancellation"},
    "voice": {
        "name": "en-US-Ava:DragonHDLatestNeural",
        "type": "azure-standard",
        "temperature": 0.8,
    },
}

Belangrijk

De "instructions" eigenschap wordt niet ondersteund wanneer u een aangepaste agent gebruikt.

De server reageert met een session.updated gebeurtenis om de sessieconfiguratie te bevestigen.

Sessie-eigenschappen

In de volgende secties worden de eigenschappen beschreven van het session object dat in het session.update bericht kan worden geconfigureerd.

Tip

Zie de referentiedocumentatie voor Azure OpenAI Realtime API-gebeurtenissen voor uitgebreide beschrijvingen van ondersteunde gebeurtenissen en eigenschappen. Dit document bevat een verwijzing naar de eigenschappen van het gebeurtenisbericht die verbeteringen zijn via de Voice Live-API.

Audio-eigenschappen invoeren

U kunt invoeraudio-eigenschappen gebruiken om de invoeraudiostroom te configureren.

Property Type Verplicht of optioneel Description
input_audio_sampling_rate integer Optional De samplingfrequentie van de invoeraudio.

De ondersteunde waarden zijn 16000 en 24000. De standaardwaarde is 24000.
input_audio_echo_cancellation object Optional Verbetert de audiokwaliteit van de invoer door de echo uit de eigen stem van het model te verwijderen zonder dat er een annulering van echo aan de clientzijde nodig is.

Stel de type eigenschap van input_audio_echo_cancellation in om echo-annulering in te schakelen.

De ondersteunde waarde type hiervoor is server_echo_cancellation, die wordt gebruikt wanneer de stem van het model via een luidspreker wordt afgespeeld aan de eindgebruiker en de microfoon de eigen stem van het model ophaalt.
input_audio_noise_reduction object Optional Verbetert de geluidskwaliteit van de invoer door achtergrondgeluiden te onderdrukken of te verwijderen.

Stel de eigenschap type in om input_audio_noise_reduction ruisonderdrukking in te schakelen.

De ondersteunde waarde type hiervoor is azure_deep_noise_suppression, die optimaliseert voor luidsprekers die het dichtst bij de microfoon liggen.

U kunt deze eigenschap instellen op near_field of far_field als u de Azure OpenAI Realtime-API gebruikt.

Hier is een voorbeeld van invoeraudio-eigenschappen in een sessieobject:

{
    "input_audio_sampling_rate": 24000,
    "input_audio_noise_reduction": {"type": "azure_deep_noise_suppression"},
    "input_audio_echo_cancellation": {"type": "server_echo_cancellation"},
}

Ruisonderdrukking en echo-annulering

Ruisonderdrukking verbetert de audiokwaliteit van de invoer door omgevingsgeluiden te onderdrukken of te verwijderen. Ruisonderdrukking helpt het model de eindgebruiker te begrijpen met een hogere nauwkeurigheid en verbetert de nauwkeurigheid van signalen, zoals onderbrekingsdetectie en einddetectie.

De annulering van de server echo verbetert de audiokwaliteit van de invoer door de echo uit de eigen stem van het model te verwijderen. Op deze manier is echo-annulering aan de clientzijde niet vereist. Server-echo-annulering is handig wanneer de stem van het model aan de eindgebruiker wordt doorgegeven via een luidspreker. Dit helpt voorkomen dat de microfoon de eigen stem van het model ophaalt.

Note

De service gaat ervan uit dat de client antwoordaudio afspeelt zodra deze deze ontvangt. Als het afspelen langer dan twee seconden wordt vertraagd, wordt de kwaliteit van echoannulering beïnvloed.

Verbeteringen in gesprekken

De Voice Live-API biedt gespreksverbeteringen om robuustheid te bieden aan de natuurlijke gespreksstroom van eindgebruikers.

Detectieparameters omdraaien

Draaidetectie is het proces van detecteren wanneer de eindgebruiker is begonnen of gestopt met spreken. De Voice Live-API is gebaseerd op de Azure OpenAI Realtime API-functionaliteit turn_detection om beurtdetectie te configureren. De azure_semantic_vad typen en azure_multilingual_semantic_vad de geavanceerde end_of_utterance_detection functies zijn belangrijke differentiators tussen de Voice Live-API en de Azure OpenAI Realtime-API.

Property Type Verplicht of optioneel Description
type string Optional Het type draaidetectiesysteem dat moet worden gebruikt. Type server_vad detecteert het begin en einde van spraak op basis van audiovolume.

Type semantic_vad maakt gebruik van een semantische classificatie om te detecteren wanneer de gebruiker klaar is met spreken, op basis van de woorden die ze hebben uitgesproken. Dit type kan alleen worden gebruikt met de gpt-realtime - en gpt-realtime-minimodellen .

Typ azure_semantic_vad en azure_semantic_vad_multilingual detecteert ook het begin en einde van spraak op basis van semantische betekenis en kan worden gebruikt met alle modellen. Verdere Semantische spraakactiviteitsdetectie (VAD) van Azure kan ook de detectie van draaibewerkingen verbeteren door vulwoorden te verwijderen om het vals alarmpercentage van barge-in te verminderen.

De standaardwaarde is server_vad.
threshold number Optional Een hogere drempelwaarde vereist een hoger betrouwbaarheidssignaal van de gebruiker die probeert te spreken.
prefix_padding_ms integer Optional De hoeveelheid audio, gemeten in milliseconden, die vóór het begin van het spraakdetectiesignaal moet worden opgenomen.
speech_duration_ms integer Optional De duur van gebruikersspraakaudio die nodig is om detectie te starten. Als deze niet is ingesteld of minder dan 80 ms, gebruikt de detector een standaardwaarde van 80 ms.
silence_duration_ms integer Optional De duur van de stilte van de gebruiker, gemeten in milliseconden, om het einde van de spraak te detecteren.
remove_filler_words booleaan Optional Bepaalt of u opvulwoorden wilt verwijderen om de fout-alarmfrequentie van barge-in te verminderen.
Als u deze eigenschap wilt inschakelen, moet deze worden ingesteld op true. De gedetecteerde vulwoorden in het Engels zijn ['ah', 'umm', 'mm', 'uh', 'huh', 'oh', 'yeah', 'hmm']. De dienst negeert deze woorden wanneer er een lopend antwoord is. De functie voor het verwijderen van opvulwoorden gaat ervan uit dat de client antwoordaudio afspeelt zodra deze wordt ontvangen.
De standaardwaarde is false.
languages string[] Optional Taal wordt gebruikt om de remove_filler_words nauwkeurigheid te verbeteren door de toegepaste talen te verminderen. Het type azure_semantic_vad ondersteunt voornamelijk Engels. Het type azure_semantic_vad_multilingual is ook beschikbaar ter ondersteuning van een grotere verscheidenheid aan talen: Engels, Spaans, Frans, Italiaans, Duits (DE), Japans, Portugees, Chinees, Koreaans, Hindi. Andere talen worden genegeerd.
create_response booleaan Optional Schakel in of uit of er een antwoord wordt gegenereerd.
eagerness string Optional Dit is een manier om te bepalen hoe geneigd het model is om de gebruiker te onderbreken door de maximale wachttijd in te stellen. Alleen beschikbaar met type semantic_vad. In de transcriptiemodus, zelfs als het model niet reageert, is dit van invloed op de manier waarop de audio wordt gesegmenteerd.
De volgende waarden zijn toegestaan:
- auto (standaard) is gelijk aan medium,
- low laat de gebruiker de tijd nemen om te spreken.
- high zal de audio zo snel mogelijk in stukken verdelen.

Als u wilt dat het model vaker reageert in de gespreksmodus, of als u sneller transcriptiegebeurtenissen wilt ontvangen in de transcriptiemodus, kunt u het eagerness-niveau instellen op high.
Als u daarentegen de gebruiker ononderbroken wilt laten spreken in de gespreksmodus, of als u grotere transcriptiefragmenten in de transcriptiemodus wilt, kunt u de bereidheid instellen op low.
interrupt_response booleaan Optional Inschakelen of uitschakelen van onderbreking bij barge-in (standaard: onwaar). Alleen beschikbaar met type azure_semantic_vad en azure_semantic_vad_multilingual.
auto_truncate booleaan Optional Automatisch afkappen bij onderbreking (standaard: onwaar).
end_of_utterance_detection object Optional Configuratie voor het detecteren van het einde van een uiting. De Voice Live-API biedt geavanceerde end-of-turn-detectie om aan te geven wanneer de eindgebruiker stopte met spreken terwijl natuurlijke pauzes mogelijk zijn. De detectie van het einde van een uiting kan voortijdige beurt-eind-signalen aanzienlijk verminderen zonder merkbare latentie voor de gebruiker toe te voegen. Het einde van de detectie van utterances kan worden gebruikt met een VAD-selectie.

Eigenschappen van end_of_utterance_detection onder andere:
- model: Het model dat moet worden gebruikt voor het detecteren van het einde van een uiting. De ondersteunde waarden zijn:
   semantic_detection_v1 Engels ondersteunen.
   semantic_detection_v1_multilingual ondersteuning voor Engels, Spaans, Frans, Italiaans, Duits (DE), Japans, Portugees, Chinees, Koreaans, Hindi.
Andere talen worden overgeslagen.
- threshold_level: Optieinstelling voor detectiedrempelniveau (low, mediumhigh endefault), de standaardwaarde is gelijk aan medium de instelling. Met een lagere instelling is de kans groter dat de zin is voltooid.
- timeout_ms: Optionele instelling voor maximale tijd in milliseconden om te wachten op meer spraak van de gebruiker. De standaardwaarde is 1000 ms.

Einde van utterancedetectie biedt momenteel geen ondersteuning voor gpt-realtime, gpt-4o-mini-realtime en phi4-mm-realtime.

Hier is een voorbeeld van detectie van het einde van een uiting in een sessieobject:

{
    "session": {
        "instructions": "You are a helpful AI assistant responding in natural, engaging language.",
        "turn_detection": {
            "type": "azure_semantic_vad",
            "threshold": 0.3,
            "prefix_padding_ms": 300,
            "speech_duration_ms":80,
            "silence_duration_ms": 500,
            "remove_filler_words": false,
            "end_of_utterance_detection": {
                "model": "semantic_detection_v1",
                "threshold_level": "default",
                "timeout_ms": 1000
            }
        }
    }
}

Audio-invoer via Spraak-naar-tekst in Azure

Spraak-naar-tekst in Azure wordt automatisch geactiveerd wanneer u een niet-multimodale model gebruikt, zoals gpt-4o.

Als u deze expliciet wilt configureren, kunt u de model op azure-speech instellen in input_audio_transcription. Dit kan handig zijn om de herkenningskwaliteit voor specifieke taalsituaties te verbeteren. Zie Voice Live-invoer en -uitvoer aanpassen voor meer informatie over de configuratie voor het aanpassen van spraakinvoer.

{
    "session": {
        "input_audio_transcription": {
            "model": "azure-speech",
            "language": "en"
        }
    }
}

Audio-uitvoer via Azure-tekst naar spraak

U kunt de voice parameter gebruiken om een standaard of aangepaste stem op te geven. De stem wordt gebruikt voor audio-uitvoer.

Het voice-object heeft de volgende eigenschappen:

Property Type Verplicht of optioneel Description
name string Required Hiermee geeft u de naam van de stem. Bijvoorbeeld: en-US-AvaNeural.
type string Required Configuratie van het type Azure-spraak tussen azure-standard en azure-custom.
temperature number Optional Hiermee geeft u de temperatuur die van toepassing is op Azure HD-stemmen. Hogere waarden bieden hogere niveaus van variabiliteit in intonatie, prosody, enzovoort.

Zie Voice Live-invoer en -uitvoer aanpassen voor meer informatie over de configuratie voor het aanpassen van spraakuitvoer.

Standaardstemmen van Azure

Hier volgt een gedeeltelijk voorbeeld van een bericht voor een standaard (azure-standard) stem:

{
  "voice": {
    "name": "en-US-AvaNeural",
    "type": "azure-standard"
  }
}

Zie Taal- en spraakondersteuning voor de Speech-service voor de volledige lijst met standaardstemmen.

Stemmen met hoge definitie van Azure

Hier volgt een voorbeeldbericht session.update voor een standaard high definition voice:

{
  "voice": {
    "name": "en-US-Ava:DragonHDLatestNeural",
    "type": "azure-standard",
    "temperature": 0.8 // optional
  }
}

Zie de documentatie voor hoge definitiestemmen voor een volledige lijst met standaardstemmen.

Note

Hoge definitie stemmen worden momenteel alleen ondersteund in de volgende regio's: southeastasia, centralindia, swedencentral, westeurope, eastus, eastus2, westus2

Spreeksnelheid

Gebruik de rate tekenreekseigenschap om de spreeksnelheid van standaard Azure-tekst-naar-spraakstemmen en aangepaste stemmen aan te passen.

De snelheidswaarde moet variëren van 0,5 tot 1,5, met hogere waarden die snellere snelheden aangeven.

{
  "voice": {
    "name": "en-US-Ava:DragonHDLatestNeural",
    "type": "azure-standard",
    "temperature": 0.8, // optional
    "rate": "1.2"
  }
}

Audiotijdstempels

Wanneer u Azure-stemmen gebruikt en output_audio_timestamp_types is geconfigureerd, retourneert de service het response.audio_timestamp.delta in het antwoord, en response.audio_timestamp.done wanneer alle tijdstempelberichten worden geretourneerd.

Als u de tijdstempels voor audio wilt configureren, kunt u het output_audio_timestamp_types bericht session.update instellen.

{
    "session": {
        "output_audio_timestamp_types": ["word"]
    }
}

Service retourneert de audiotijdstempels in het antwoord wanneer de audio wordt gegenereerd.

{
    "event_id": "<event_id>",
    "type": "response.audio_timestamp.delta",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
    "output_index": 0,
    "content_index": 0,
    "audio_offset_ms": 490,
    "audio_duration_ms": 387,
    "text": "end",
    "timestamp_type": "word"
}

En er wordt een response.audio_timestamp.done bericht verzonden wanneer alle tijdstempels worden geretourneerd.

{
    "event_id": "<event_id>",
    "type": "response.audio_timestamp.done",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
}

Viseme

Een viseme is de visuele beschrijving van een phoneme in gesproken taal. Het definieert de positie van het gezicht en de mond terwijl een persoon spreekt.

U kunt Azure Standaard Voice of Azure Aangepaste Spraak gebruiken met animation.outputs ingesteld op {"viseme_id"}. De service retourneert de response.animation_viseme.delta in het antwoord en response.animation_viseme.done zodra alle viseme-berichten zijn geretourneerd.

Tip

Zie de documentatie over viseme-elementen voor meer informatie over viseme via Speech Synthesis Markup Language (SSML).

Als u het viseme wilt configureren, kunt u het animation.outputs in het session.update bericht instellen. De animation.outputs-parameter is optioneel. Hiermee configureert u welke animatie-uitvoer moet worden geretourneerd. Momenteel ondersteunt het alleen viseme_id.

{
  "type": "session.update",
  "event_id": "your-session-id",
  "session": {
    "voice": {
      "name": "en-US-AvaNeural",
      "type": "azure-standard",
    },
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful AI assistant responding in natural, engaging language.",
    "turn_detection": {
        "type": "server_vad"
    },
    "output_audio_timestamp_types": ["word"], // optional
    "animation": {
        "outputs": ["viseme_id"], // optional
    },
  }
}

De output_audio_timestamp_types-parameter is optioneel. Hiermee configureert u welke audiotijdstempels moeten worden geretourneerd voor gegenereerde audio. Momenteel ondersteunt het alleen word.

De service retourneert de viseme-uitlijning in het antwoord wanneer de audio wordt gegenereerd.

{
    "event_id": "<event_id>",
    "type": "response.animation_viseme.delta",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
    "output_index": 0,
    "content_index": 0,
    "audio_offset_ms": 455,
    "viseme_id": 20
}

En een response.animation_viseme.done bericht wordt verzonden wanneer alle visemeberichten zijn geretourneerd.

{
    "event_id": "<event_id>",
    "type": "response.animation_viseme.done",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
}

Avatar van tekst-naar-spraak van Azure

Tekst-naar-spraak-avatar converteert tekst naar een digitale video van een fotorealistisch mens (een standaard avatar of een aangepaste tekst naar spraak avatar) die spreekt met een natuurlijke stem.

U kunt de avatar parameter gebruiken om een standaard- of aangepaste avatar op te geven. De avatar wordt gesynchroniseerd met de audio-uitvoer.

Er kan een avatar parameter worden opgegeven om avataruitvoer in te schakelen die wordt gesynchroniseerd met de audio-uitvoer:

{
  "session": {
    "avatar": {
      "character": "lisa",
      "style": "casual-sitting",
      "customized": false,
      "ice_servers": [
        {
          "urls": ["REDACTED"],
          "username": "",
          "credential": ""
        }
      ],
      "video": {
        "bitrate": 2000000,
        "codec": "h264",
        "crop": {
          "top_left": [560, 0],
          "bottom_right": [1360, 1080],
        },
        "resolution": {
          "width": 1080,
          "height": 1920,
        },
        "background": {
          "color": "#00FF00FF"
          // "image_url": "https://example.com/example.jpg"
        }
      }
    }
  }
}

Het ice_servers veld is optioneel. Als u deze niet opgeeft, retourneert de service de serverspecifieke ICE-servers als session.updated reactie. En u moet de serverspecifieke ICE-servers gebruiken om de lokale ICE-kandidaten te genereren.

Verzend de client-SDP nadat ICE-kandidaten zijn verzameld.

{
    "type": "session.avatar.connect",
    "client_sdp": "your-client-sdp"
}

En de service reageert met de server-SDP.

{
    "type": "session.avatar.connecting",
    "server_sdp": "your-server-sdp"
}

Vervolgens kunt u de avatar verbinden met de server-SDP.

Note

Azure text to speech avatar wordt momenteel ondersteund in beperkte regio's. Zie de tabel Speech-serviceregio's voor de huidige lijst met ondersteunde regio's.

Verwante inhoud

  • Last updated on