REST API voor tekst-naar-spraak
Met de Speech-service kunt u tekst converteren naar gesynthetiseerde spraak en een lijst met ondersteunde stemmen voor een regio ophalen met behulp van een REST API. In dit artikel leert u meer over autorisatieopties, queryopties, het structuren van een aanvraag en het interpreteren van een antwoord.
Tip
Use cases for the text to speech REST API are limited. Gebruik deze alleen in gevallen waarin u de Speech SDK niet kunt gebruiken. Met de Speech SDK kunt u zich bijvoorbeeld abonneren op gebeurtenissen voor meer inzicht in de tekst in spraakverwerking en resultaten.
De tekst naar spraak REST API ondersteunt neurale tekst naar spraakstemmen in veel landinstellingen. Elk beschikbaar eindpunt is gekoppeld aan een regio. Een Spraak-resourcesleutel voor het eindpunt of de regio die u wilt gebruiken, is vereist. Hier volgen koppelingen naar meer informatie:
- Zie Taal- en spraakondersteuning voor de Speech-service voor een volledige lijst met stemmen.
- Zie ondersteunde regio's van de Speech-service voor meer informatie over regionale beschikbaarheid.
- Zie dit artikel over onafhankelijke clouds voor Azure Government en Microsoft Azure beheerd door 21Vianet-eindpunten.
Belangrijk
De kosten variëren voor vooraf gemaakte neurale stemmen (neurale stemmen genoemd op de pagina met prijzen) en aangepaste neurale stemmen (aangepaste neurale stemmen genoemd op de pagina met prijzen). Zie prijzen voor de Speech-service voor meer informatie.
Voordat u de tekst voor spraak-REST API gebruikt, moet u weten dat u een tokenuitwisseling moet voltooien als onderdeel van verificatie voor toegang tot de service. Zie Verificatie voor meer informatie.
Een lijst met stemmen ophalen
U kunt het tts.speech.microsoft.com/cognitiveservices/voices/list eindpunt gebruiken om een volledige lijst met stemmen voor een specifieke regio of eindpunt op te halen. Voorvoegsel voor het eindpunt van de lijst met stemmen met een regio om een lijst met stemmen voor die regio op te halen. Als u bijvoorbeeld een lijst met stemmen voor de westus regio wilt ophalen, gebruikt u het https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list eindpunt. Zie de documentatie voor regio's voor een lijst met alle ondersteunde regio's .
Notitie
Stemmen en stijlen in preview zijn alleen beschikbaar in drie serviceregio's: VS - oost , Europa - west en Azië - zuidoost.
Aanvraagheaders
Deze tabel bevat vereiste en optionele kopteksten voor tekst-naar-spraakaanvragen:
| Koptekst | Beschrijving | Vereist of optioneel |
|---|---|---|
Ocp-Apim-Subscription-Key |
Uw Spraak-resourcesleutel. | Deze header of Authorization is vereist. |
Authorization |
Een autorisatietoken voorafgegaan door het woord Bearer. Zie Verificatie voor meer informatie. |
Deze header of Ocp-Apim-Subscription-Key is vereist. |
Aanvraagtekst
Er is geen hoofdtekst vereist voor GET aanvragen naar dit eindpunt.
Voorbeeldaanvraag
Voor deze aanvraag is alleen een autorisatieheader vereist:
GET /cognitiveservices/voices/list HTTP/1.1
Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Hier volgt een voorbeeld van een curl-opdracht:
curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'
Voorbeeldrespons
U moet een antwoord ontvangen met een JSON-hoofdtekst met alle ondersteunde landinstellingen, stemmen, geslacht, stijlen en andere details. De WordsPerMinute eigenschap voor elke stem kan worden gebruikt om de lengte van de uitvoerspraak te schatten. In dit JSON-voorbeeld ziet u gedeeltelijke resultaten om de structuur van een antwoord te illustreren:
[
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyNeural)",
"DisplayName": "Jenny",
"LocalName": "Jenny",
"ShortName": "en-US-JennyNeural",
"Gender": "Female",
"Locale": "en-US",
"LocaleName": "English (United States)",
"StyleList": [
"assistant",
"chat",
"customerservice",
"newscast",
"angry",
"cheerful",
"sad",
"excited",
"friendly",
"terrified",
"shouting",
"unfriendly",
"whispering",
"hopeful"
],
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"ExtendedPropertyMap": {
"IsHighQuality48K": "True"
},
"WordsPerMinute": "152"
},
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyMultilingualNeural)",
"DisplayName": "Jenny Multilingual",
"LocalName": "Jenny Multilingual",
"ShortName": "en-US-JennyMultilingualNeural",
"Gender": "Female",
"Locale": "en-US",
"LocaleName": "English (United States)",
"SecondaryLocaleList": [
"de-DE",
"en-AU",
"en-CA",
"en-GB",
"es-ES",
"es-MX",
"fr-CA",
"fr-FR",
"it-IT",
"ja-JP",
"ko-KR",
"pt-BR",
"zh-CN"
],
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"WordsPerMinute": "190"
},
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (ga-IE, OrlaNeural)",
"DisplayName": "Orla",
"LocalName": "Orla",
"ShortName": "ga-IE-OrlaNeural",
"Gender": "Female",
"Locale": "ga-IE",
"LocaleName": "Irish (Ireland)",
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"WordsPerMinute": "139"
},
// Redacted for brevity
{
"Name": "Microsoft Server Speech Text to Speech Voice (zh-CN, YunxiNeural)",
"DisplayName": "Yunxi",
"LocalName": "云希",
"ShortName": "zh-CN-YunxiNeural",
"Gender": "Male",
"Locale": "zh-CN",
"LocaleName": "Chinese (Mandarin, Simplified)",
"StyleList": [
"narration-relaxed",
"embarrassed",
"fearful",
"cheerful",
"disgruntled",
"serious",
"angry",
"sad",
"depressed",
"chat",
"assistant",
"newscast"
],
"SampleRateHertz": "24000",
"VoiceType": "Neural",
"Status": "GA",
"RolePlayList": [
"Narrator",
"YoungAdultMale",
"Boy"
],
"WordsPerMinute": "293"
},
// Redacted for brevity
]
HTTP-statuscode
De HTTP-statuscode voor elk antwoord duidt op geslaagde of veelvoorkomende fouten.
| HTTP-statuscode | Beschrijving | Mogelijke reden |
|---|---|---|
| 200 | OK | De aanvraag is geslaagd. |
| 400 | Ongeldige aanvraag | Een vereiste parameter ontbreekt, leeg of null. Of de waarde die is doorgegeven aan een vereiste of optionele parameter, is ongeldig. Een veelvoorkomende reden is een header die te lang is. |
| 401 | Niet geautoriseerd | De aanvraag is niet geautoriseerd. Zorg ervoor dat uw resourcesleutel of token geldig is en in de juiste regio. |
| 429 | Te veel aanvragen | U hebt het quotum of de frequentie van aanvragen overschreden die zijn toegestaan voor uw resource. |
| 502 | Ongeldige gateway | Er is een probleem aan de netwerk- of serverzijde. Deze status kan ook ongeldige headers aangeven. |
Tekst naar spraak converteren
Met cognitiveservices/v1 het eindpunt kunt u tekst converteren naar spraak met behulp van SSML (Speech Synthesis Markup Language).
Regio's en eindpunten
Deze regio's worden ondersteund voor tekst-naar-spraak via de REST API. Zorg ervoor dat u het eindpunt selecteert dat overeenkomt met uw spraakresourceregio.
Vooraf samengestelde neurale stemmen
Gebruik deze tabel om de beschikbaarheid van neurale stemmen per regio of eindpunt te bepalen:
| Regio | Eindpunt |
|---|---|
| Australië - oost | https://australiaeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Brazilië - zuid | https://brazilsouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Canada - midden | https://canadacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Central US | https://centralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Azië - oost | https://eastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| VS - oost | https://eastus.tts.speech.microsoft.com/cognitiveservices/v1 |
| VS - oost 2 | https://eastus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| Frankrijk - centraal | https://francecentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Duitsland - west-centraal | https://germanywestcentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| India - centraal | https://centralindia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Japan - oost | https://japaneast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Japan - west | https://japanwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Jio India West | https://jioindiawest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Korea - centraal | https://koreacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| VS - noord-centraal | https://northcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Europa - noord | https://northeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| Noorwegen - oost | https://norwayeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| VS - zuid-centraal | https://southcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Azië - zuidoost | https://southeastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Zweden - centraal | https://swedencentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Zwitserland - noord | https://switzerlandnorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Zwitserland - west | https://switzerlandwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| VAE - noord | https://uaenorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| US Gov - Arizona | https://usgovarizona.tts.speech.azure.us/cognitiveservices/v1 |
| VS (overheid) - Virginia | https://usgovvirginia.tts.speech.azure.us/cognitiveservices/v1 |
| Verenigd Koninkrijk Zuid | https://uksouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| VS - west-centraal | https://westcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Europa -west | https://westeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| VS - west | https://westus.tts.speech.microsoft.com/cognitiveservices/v1 |
| VS - west 2 | https://westus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| US - west 3 | https://westus3.tts.speech.microsoft.com/cognitiveservices/v1 |
Tip
Stemmen in preview zijn alleen beschikbaar in deze drie regio's: VS - oost , Europa - west en Azië - zuidoost.
Aangepaste neurale stemmen
Als u een aangepast neuraal spraaklettertype hebt gemaakt, gebruikt u het eindpunt dat u hebt gemaakt. U kunt ook de volgende eindpunten gebruiken. Vervang door {deploymentId} de implementatie-id voor uw neurale spraakmodel.
| Regio | Training | Implementatie | Eindpunt |
|---|---|---|---|
| Australië - oost | Ja | Ja | https://australiaeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Brazilië - zuid | Nr. | Ja | https://brazilsouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Canada - midden | Nr. | Ja | https://canadacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Central US | Nr. | Ja | https://centralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Azië - oost | Nr. | Ja | https://eastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| VS - oost | Ja | Ja | https://eastus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| VS - oost 2 | Ja | Ja | https://eastus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Frankrijk - centraal | Nr. | Ja | https://francecentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Duitsland - west-centraal | Nr. | Ja | https://germanywestcentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| India - centraal | Ja | Ja | https://centralindia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Japan East | Ja | Ja | https://japaneast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Japan - west | Nr. | Ja | https://japanwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Jio India West | Nr. | Ja | https://jioindiawest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Korea - centraal | Ja | Ja | https://koreacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| VS - noord-centraal | Nr. | Ja | https://northcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Europa - noord | Ja | Ja | https://northeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Noorwegen - oost | Nr. | Ja | https://norwayeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Zuid-Afrika - noord | Nr. | Ja | https://southafricanorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| VS - zuid-centraal | Ja | Ja | https://southcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Azië - zuidoost | Ja | Ja | https://southeastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Zwitserland - noord | Nr. | Ja | https://switzerlandnorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Zwitserland - west | Nr. | Ja | https://switzerlandwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| VAE - noord | Nr. | Ja | https://uaenorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Verenigd Koninkrijk Zuid | Ja | Ja | https://uksouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| VS - west-centraal | Nr. | Ja | https://westcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Europa -west | Ja | Ja | https://westeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| VS - west | Ja | Ja | https://westus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| VS - west 2 | Ja | Ja | https://westus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| US - west 3 | Nr. | Ja | https://westus3.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
Notitie
De voorgaande regio's zijn beschikbaar voor het hosten van neurale spraakmodellen en realtimesynthese. Aangepaste neurale spraaktraining is alleen beschikbaar in sommige regio's. Maar gebruikers kunnen eenvoudig een neuraal spraakmodel van deze regio's kopiëren naar andere regio's in de voorgaande lijst.
API voor lange audio
De Long Audio-API is beschikbaar in meerdere regio's met unieke eindpunten:
| Regio | Eindpunt |
|---|---|
| Australië - oost | https://australiaeast.customvoice.api.speech.microsoft.com |
| VS - oost | https://eastus.customvoice.api.speech.microsoft.com |
| India - centraal | https://centralindia.customvoice.api.speech.microsoft.com |
| VS - zuid-centraal | https://southcentralus.customvoice.api.speech.microsoft.com |
| Azië - zuidoost | https://southeastasia.customvoice.api.speech.microsoft.com |
| Verenigd Koninkrijk Zuid | https://uksouth.customvoice.api.speech.microsoft.com |
| Europa -west | https://westeurope.customvoice.api.speech.microsoft.com |
Aanvraagheaders
Deze tabel bevat vereiste en optionele kopteksten voor tekst-naar-spraakaanvragen:
| Koptekst | Beschrijving | Vereist of optioneel |
|---|---|---|
Authorization |
Een autorisatietoken voorafgegaan door het woord Bearer. Zie Verificatie voor meer informatie. |
Vereist |
Content-Type |
Hiermee geeft u het inhoudstype voor de opgegeven tekst. Geaccepteerde waarde: application/ssml+xml. |
Vereist |
X-Microsoft-OutputFormat |
Hiermee geeft u de audio-uitvoerindeling. Zie Audio-uitvoer voor een volledige lijst met geaccepteerde waarden. | Vereist |
User-Agent |
De naam van de toepassing. De opgegeven waarde moet uit minder dan 255 tekens bestaan. | Vereist |
Aanvraagtekst
Als u een aangepaste neurale stem gebruikt, kan de hoofdtekst van een aanvraag worden verzonden als tekst zonder opmaak (ASCII of UTF-8). Anders wordt de hoofdtekst van elke POST aanvraag verzonden als SSML. Met SSML kunt u de stem en taal van de gesynthetiseerde spraak kiezen die door de functie tekst naar spraak wordt geretourneerd. Zie Taal- en spraakondersteuning voor de Speech-service voor een volledige lijst met ondersteunde stemmen.
Voorbeeldaanvraag
Deze HTTP-aanvraag maakt gebruik van SSML om de spraak en taal op te geven. Als de lichaamslengte lang is en de resulterende audio langer is dan 10 minuten, wordt deze afgekapt tot 10 minuten. Met andere woorden, de audiolengte mag niet langer zijn dan 10 minuten.
POST /cognitiveservices/v1 HTTP/1.1
X-Microsoft-OutputFormat: riff-24khz-16bit-mono-pcm
Content-Type: application/ssml+xml
Host: westus.tts.speech.microsoft.com
Content-Length: <Length>
Authorization: Bearer [Base64 access_token]
User-Agent: <Your application name>
<speak version='1.0' xml:lang='en-US'><voice xml:lang='en-US' xml:gender='Male'
name='en-US-ChristopherNeural'>
I'm excited to try text to speech!
</voice></speak>
* Voor de lengte van de inhoud moet u uw eigen inhoudslengte gebruiken. In de meeste gevallen wordt deze waarde automatisch berekend.
HTTP-statuscode
De HTTP-statuscode voor elk antwoord duidt op geslaagde of veelvoorkomende fouten:
| HTTP-statuscode | Beschrijving | Mogelijke reden |
|---|---|---|
| 200 | OK | De aanvraag is geslaagd. De hoofdtekst van het antwoord is een audiobestand. |
| 400 | Ongeldige aanvraag | Een vereiste parameter ontbreekt, leeg of null. Of de waarde die is doorgegeven aan een vereiste of optionele parameter, is ongeldig. Een veelvoorkomende reden is een header die te lang is. |
| 401 | Niet geautoriseerd | De aanvraag is niet geautoriseerd. Zorg ervoor dat uw Spraak-resourcesleutel of -token geldig is en zich in de juiste regio bevindt. |
| 415 | Niet-ondersteund mediatype | Het is mogelijk dat de verkeerde Content-Type waarde is opgegeven. Content-Type moet worden ingesteld op application/ssml+xml. |
| 429 | Te veel aanvragen | U hebt het quotum of de frequentie van aanvragen overschreden die zijn toegestaan voor uw resource. |
| 502 | Ongeldige gateway | Er is een probleem aan de netwerk- of serverzijde. Deze status kan ook ongeldige headers aangeven. |
Als de HTTP-status is 200 OK, bevat de hoofdtekst van het antwoord een audiobestand in de aangevraagde indeling. Dit bestand kan worden afgespeeld wanneer het wordt overgedragen, opgeslagen in een buffer of opgeslagen in een bestand.
Audio-uitvoer
De ondersteunde streaming- en niet-streaming audio-indelingen worden in elke aanvraag als header X-Microsoft-OutputFormat verzonden. Elke indeling bevat een bitsnelheid en coderingstype. De Speech-service ondersteunt audio-uitgangen van 48 kHz, 24 kHz, 16 kHz en 8 kHz. Elk vooraf samengesteld neurale spraakmodel is beschikbaar op 24 kHz en 48kHz.
amr-wb-16000hz
audio-16khz-16bit-32kbps-mono-opus
audio-16khz-32kbitrate-mono-mp3
audio-16khz-64kbitrate-mono-mp3
audio-16khz-128kbitrate-mono-mp3
audio-24khz-16bit-24kbps-mono-opus
audio-24khz-16bit-48kbps-mono-opus
audio-24khz-48kbitrate-mono-mp3
audio-24khz-96kbitrate-mono-mp3
audio-24khz-160kbitrate-mono-mp3
audio-48khz-96kbitrate-mono-mp3
audio-48khz-192kbitrate-mono-mp3
ogg-16khz-16bit-mono-opus
ogg-24khz-16bit-mono-opus
ogg-48khz-16bit-mono-opus
raw-8khz-8bit-mono-alaw
raw-8khz-8bit-mono-mulaw
raw-8khz-16bit-mono-pcm
raw-16khz-16bit-mono-pcm
raw-16khz-16bit-mono-truesilk
raw-22050hz-16bit-mono-pcm
raw-24khz-16bit-mono-pcm
raw-24khz-16bit-mono-truesilk
raw-44100hz-16bit-mono-pcm
raw-48khz-16bit-mono-pcm
webm-16khz-16bit-mono-opus
webm-24khz-16bit-24kbps-mono-opus
webm-24khz-16bit-mono-opus
Notitie
Als u een uitvoerindeling van 48 kHz selecteert, wordt het spraakmodel met 48 kHz dienovereenkomstig aangeroepen. De steekproefsnelheden behalve 24 kHz en 48kHz kunnen worden verkregen via upsampling of downsampling bij het synthetiseren, bijvoorbeeld 44,1kHz wordt downsampled van 48kHz.
Als de geselecteerde spraak- en uitvoerindeling verschillende bitsnelheden hebben, wordt de audio indien nodig opnieuw gesampled. U kunt de ogg-24khz-16bit-mono-opus indeling decoderen met behulp van de Opus-codec.
Verificatie
Voor elke aanvraag is een autorisatieheader vereist. In deze tabel ziet u welke headers worden ondersteund voor elke functie:
| Ondersteunde autorisatieheader | Spraak-naar-tekst | Tekst naar spraak |
|---|---|---|
Ocp-Apim-Subscription-Key |
Ja | Ja |
Authorization: Bearer |
Ja | Ja |
Wanneer u de Ocp-Apim-Subscription-Key header gebruikt, moet alleen uw resourcesleutel worden opgegeven. Voorbeeld:
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
Wanneer u de Authorization: Bearer header gebruikt, moet u een aanvraag indienen bij het issueToken eindpunt. In deze aanvraag wisselt u uw resourcesleutel uit voor een toegangstoken dat tien minuten geldig is.
Een andere optie is om Microsoft Entra-verificatie te gebruiken die ook gebruikmaakt van de Authorization: Bearer header, maar met een token dat is uitgegeven via Microsoft Entra-id. Zie Microsoft Entra-verificatie gebruiken.
Een toegangstoken ophalen
Als u een toegangstoken wilt ophalen, moet u een aanvraag indienen bij het issueToken eindpunt met behulp van Ocp-Apim-Subscription-Key en uw resourcesleutel.
Het issueToken eindpunt heeft deze indeling:
https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken
Vervang <REGION_IDENTIFIER> door de id die overeenkomt met de regio van uw abonnement.
Gebruik de volgende voorbeelden om uw toegangstokenaanvraag te maken.
HTTP-voorbeeld
Dit voorbeeld is een eenvoudige HTTP-aanvraag om een token op te halen. Vervang YOUR_SUBSCRIPTION_KEY door uw resourcesleutel voor de Speech-service. Als uw abonnement zich niet in de regio VS - west bevindt, vervangt u de header door de Host hostnaam van uw regio.
POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: eastus.api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0
De hoofdtekst van het antwoord bevat het toegangstoken in de JSON Web Token-indeling (JWT).
Voorbeeld van PowerShell
Dit voorbeeld is een eenvoudig PowerShell-script om een toegangstoken op te halen. Vervang YOUR_SUBSCRIPTION_KEY door uw resourcesleutel voor de Speech-service. Zorg ervoor dat u het juiste eindpunt gebruikt voor de regio die overeenkomt met uw abonnement. Dit voorbeeld is momenteel ingesteld op VS - west.
$FetchTokenHeader = @{
'Content-type'='application/x-www-form-urlencoded';
'Content-Length'= '0';
'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY'
}
$OAuthToken = Invoke-RestMethod -Method POST -Uri https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken
-Headers $FetchTokenHeader
# show the token received
$OAuthToken
cURL-voorbeeld
cURL is een opdrachtregelprogramma dat beschikbaar is in Linux (en in de Windows-subsysteem voor Linux). Deze cURL-opdracht illustreert hoe u een toegangstoken kunt ophalen. Vervang YOUR_SUBSCRIPTION_KEY door uw resourcesleutel voor de Speech-service. Zorg ervoor dat u het juiste eindpunt gebruikt voor de regio die overeenkomt met uw abonnement. Dit voorbeeld is momenteel ingesteld op VS - west.
curl -v -X POST \
"https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-Length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"
C#-voorbeeld
Deze C#-klasse laat zien hoe u een toegangstoken kunt verkrijgen. Geef uw resourcesleutel door voor de Speech-service wanneer u de klasse instantiëren. Als uw abonnement zich niet in de regio VS - west bevindt, wijzigt u de waarde zodat FetchTokenUri deze overeenkomt met de regio voor uw abonnement.
public class Authentication
{
public static readonly string FetchTokenUri =
"https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken";
private string subscriptionKey;
private string token;
public Authentication(string subscriptionKey)
{
this.subscriptionKey = subscriptionKey;
this.token = FetchTokenAsync(FetchTokenUri, subscriptionKey).Result;
}
public string GetAccessToken()
{
return this.token;
}
private async Task<string> FetchTokenAsync(string fetchUri, string subscriptionKey)
{
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
UriBuilder uriBuilder = new UriBuilder(fetchUri);
var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
return await result.Content.ReadAsStringAsync();
}
}
}
Python-voorbeeld
# Request module must be installed.
# Run pip install requests if necessary.
import requests
subscription_key = 'REPLACE_WITH_YOUR_KEY'
def get_token(subscription_key):
fetch_token_url = 'https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken'
headers = {
'Ocp-Apim-Subscription-Key': subscription_key
}
response = requests.post(fetch_token_url, headers=headers)
access_token = str(response.text)
print(access_token)
Een toegangstoken gebruiken
Het toegangstoken moet als header Authorization: Bearer <TOKEN> naar de service worden verzonden. Elk toegangstoken is 10 minuten geldig. U kunt op elk gewenst moment een nieuw token krijgen, maar om netwerkverkeer en latentie te minimaliseren, raden we u aan om hetzelfde token negen minuten te gebruiken.
Hier volgt een voorbeeld van een HTTP-aanvraag voor de REST API voor spraak naar tekst voor korte audio:
POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive
// Message body here...
Microsoft Entra-verificatie gebruiken
Als u Microsoft Entra-verificatie wilt gebruiken met de SPEECH to text REST API voor korte audio, moet u een toegangstoken maken. De stappen voor het verkrijgen van het toegangstoken dat bestaat uit de resource-id en het Microsoft Entra-toegangstoken zijn hetzelfde als bij het gebruik van de Speech SDK. Volg de stappen hier : Microsoft Entra-verificatie gebruiken
- Een spraakresource maken
- De Spraak-resource configureren voor Microsoft Entra-verificatie
- Een Microsoft Entra-toegangstoken ophalen
- De spraakresource-id ophalen
Nadat de resource-id en het Microsoft Entra-toegangstoken zijn verkregen, kan het werkelijke toegangstoken worden samengesteld volgens deze indeling:
aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN
U moet het voorvoegsel 'aad#' en het scheidingsteken '#' (hash) tussen de resource-id en het toegangstoken opnemen.
Hier volgt een voorbeeld van een HTTP-aanvraag voor de REST API voor spraak naar tekst voor korte audio:
POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive
// Message body here...
Voor meer informatie over Microsoft Entra-toegangstokens, inclusief levensduur van tokens, gaat u naar Access-tokens in het Microsoft Identity Platform.