Freigeben über


Sprachsynthese-REST-API

Die Speech-Dienste ermöglichen es Ihnen, Text in synthetisierte Sprache zu konvertieren und eine Liste der unterstützten Stimmen für eine Region unter Verwendung einer REST-API zu erhalten. In diesem Artikel erfahren Sie mehr über Autorisierungsoptionen, Abfrageoptionen, das Strukturieren einer Anforderung und das Interpretieren einer Antwort.

Tipp

Die Anwendungsfälle für die Sprachsynthese-REST-API sind eingeschränkt. Verwenden Sie sie nur in Fällen, in denen Sie das Speech SDK nicht verwenden können. Beispielsweise können Sie mit dem Speech SDK Ereignisse abonnieren, um mehr Erkenntnisse zur Verarbeitung und den Ergebnissen der Sprachsynthese zu erhalten.

Der Text zur Sprachausgabe-REST-API unterstützt neuralen Text zu Sprachstimmzeichen in vielen Gebietsschemas. Jeder verfügbare Endpunkt ist einer Region zugeordnet. Es ist ein Speech-Ressourcenschlüssel für den Endpunkt bzw. die Region erforderlich, den/die Sie verwenden möchten. Hier finden Sie Links zu weiteren Informationen:

Wichtig

Die Kosten variieren für vordefinierte neuronale Stimmen (auf der Preisseite als Neuronal bezeichnet) und benutzerdefinierte neuronale Stimmen (auf der Preisseite als Benutzerdefiniert bezeichnet). Weitere Informationen finden Sie unter Preise für den Speech-Dienst.

Bevor Sie auf die Sprachsynthese-REST-API zugreifen können, müssen Sie einen Tokenaustausch im Rahmen der Authentifizierung durchführen. Weitere Informationen finden Sie unter Authentifizierung.

Abrufen einer Liste von Stimmen

Sie können den Endpunkt tts.speech.microsoft.com/cognitiveservices/voices/list verwenden, um eine vollständige Liste der Stimmen für eine bestimmte Region oder einen bestimmten Endpunkt zu erhalten. Stellen Sie dem Endpunkt für die Stimmenliste eine Region voran, um eine Liste der Stimmen für diese Region abzurufen. Wenn Sie beispielsweise eine Liste der Stimmen für die Region westus abrufen möchten, verwenden Sie den Endpunkt https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list. Eine Liste aller unterstützten Regionen finden Sie in der Dokumentation zu Regionen.

Hinweis

Stimmen und Stile in der Vorschauversion sind nur in drei Dienstregionen verfügbar: „USA, Osten“, „Europa, Westen“ und „Asien, Südosten“.

Anforderungsheader

Diese Tabelle führt die erforderlichen und optionalen Header für Sprachsynthese-Anforderungen auf:

Header BESCHREIBUNG Erforderlich oder optional
Ocp-Apim-Subscription-Key Ihr Speech-Ressourcenschlüssel. Entweder dieser Header oder Authorization ist erforderlich.
Authorization Ein Autorisierungstoken, dem das Wort Bearer vorangestellt ist. Weitere Informationen finden Sie unter Authentifizierung. Entweder dieser Header oder Ocp-Apim-Subscription-Key ist erforderlich.

Anforderungstext

Ein Text ist nicht erforderlich für GET-Anforderungen an diesen Endpunkt.

Beispiel für eine Anforderung

Diese Anforderung erfordert nur einen Autorisierungsheader.

GET /cognitiveservices/voices/list HTTP/1.1

Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY

Hier ist ein curl-Beispielbefehl:

curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'

Beispiel für eine Antwort

Sie sollten eine Antwort mit einem JSON-Textkörper erhalten, der alle unterstützten Gebietsschemas, Stimmen, Geschlecht, Stile und weitere Details enthält. Die WordsPerMinute-Eigenschaft für jede Stimme kann verwendet werden, um die Länge der Sprachausgabe zu schätzen. Dieses JSON-Beispiel zeigt Teilergebnisse, um die Struktur einer Antwort zu veranschaulichen:

[  
    // 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-Statuscodes

Der HTTP-Statuscode jeder Antwort zeigt den Erfolg oder allgemeine Fehler an.

HTTP-Statuscode BESCHREIBUNG Mögliche Ursache
200 OK Die Anforderung wurde erfolgreich gesendet.
400 Ungültige Anforderung Ein erforderlicher Parameter fehlt, ist leer oder Null. Oder der an einen erforderlichen oder optionalen Parameter übergebene Wert ist ungültig. Ein häufiger Grund ist ein zu langer Header.
401 Nicht autorisiert Die Anforderung ist nicht autorisiert. Vergewissern Sie sich, dass Ihr Ressourcenschlüssel oder Token gültig ist und sich in der richtigen Region befindet.
429 Zu viele Anforderungen Sie haben das Kontingent oder die Rate der für Ihre Ressource zulässigen Anforderungen überschritten.
502 Ungültiger Gateway Es liegt ein Netzwerkproblem oder serverseitiges Problem vor. Dieser Status kann auch auf ungültige Header hinweisen.

Konvertieren von Text in Sprache

Der Endpunkt cognitiveservices/v1 ermöglicht es Ihnen Text mit der Speech Synthesis Markup Language (SSML) in Sprache zu konvertieren.

Regionen und Endpunkte

Diese Regionen werden für die Sprachsynthese über die REST-API unterstützt. Achten Sie darauf, dass Sie den Endpunkt für die Region Ihrer Speech-Ressource auswählen.

Vordefinierte neuronale Stimmen

Verwenden Sie diese Tabelle, um die Verfügbarkeit von neuronalen Stimmen nach Region oder Endpunkt zu ermitteln:

Region Endpunkt
Australien (Osten) https://australiaeast.tts.speech.microsoft.com/cognitiveservices/v1
Brasilien Süd https://brazilsouth.tts.speech.microsoft.com/cognitiveservices/v1
Kanada, Mitte https://canadacentral.tts.speech.microsoft.com/cognitiveservices/v1
USA, Mitte https://centralus.tts.speech.microsoft.com/cognitiveservices/v1
Asien, Osten https://eastasia.tts.speech.microsoft.com/cognitiveservices/v1
East US https://eastus.tts.speech.microsoft.com/cognitiveservices/v1
USA (Ost) 2 https://eastus2.tts.speech.microsoft.com/cognitiveservices/v1
Frankreich, Mitte https://francecentral.tts.speech.microsoft.com/cognitiveservices/v1
Deutschland, Westen-Mitte https://germanywestcentral.tts.speech.microsoft.com/cognitiveservices/v1
Indien, Mitte https://centralindia.tts.speech.microsoft.com/cognitiveservices/v1
Japan, Osten https://japaneast.tts.speech.microsoft.com/cognitiveservices/v1
Japan, Westen https://japanwest.tts.speech.microsoft.com/cognitiveservices/v1
Jio Indien, Westen https://jioindiawest.tts.speech.microsoft.com/cognitiveservices/v1
Korea, Mitte https://koreacentral.tts.speech.microsoft.com/cognitiveservices/v1
USA Nord Mitte https://northcentralus.tts.speech.microsoft.com/cognitiveservices/v1
Nordeuropa https://northeurope.tts.speech.microsoft.com/cognitiveservices/v1
Norwegen, Osten https://norwayeast.tts.speech.microsoft.com/cognitiveservices/v1
USA Süd Mitte https://southcentralus.tts.speech.microsoft.com/cognitiveservices/v1
Asien, Südosten https://southeastasia.tts.speech.microsoft.com/cognitiveservices/v1
Schweden, Mitte https://swedencentral.tts.speech.microsoft.com/cognitiveservices/v1
Schweiz, Norden https://switzerlandnorth.tts.speech.microsoft.com/cognitiveservices/v1
Schweiz, Westen https://switzerlandwest.tts.speech.microsoft.com/cognitiveservices/v1
Vereinigte Arabische Emirate, Norden https://uaenorth.tts.speech.microsoft.com/cognitiveservices/v1
US Gov Arizona https://usgovarizona.tts.speech.azure.us/cognitiveservices/v1
US Government, Virginia https://usgovvirginia.tts.speech.azure.us/cognitiveservices/v1
UK, Süden https://uksouth.tts.speech.microsoft.com/cognitiveservices/v1
USA, Westen-Mitte https://westcentralus.tts.speech.microsoft.com/cognitiveservices/v1
Europa, Westen https://westeurope.tts.speech.microsoft.com/cognitiveservices/v1
USA (Westen) https://westus.tts.speech.microsoft.com/cognitiveservices/v1
USA, Westen 2 https://westus2.tts.speech.microsoft.com/cognitiveservices/v1
USA, Westen 3 https://westus3.tts.speech.microsoft.com/cognitiveservices/v1

Tipp

Stimmen in der Vorschauversion sind nur in diesen drei Regionen verfügbar: „USA, Osten“, „Europa, Westen“ und „Asien, Südosten“.

Benutzerdefinierte neuronale Stimmen

Wenn Sie einen benutzerdefinierten neuronalen Voicefont erstellt haben, verwenden Sie den von Ihnen erstellten Endpunkt. Sie können auch die folgenden Endpunkte verwenden. Ersetzen Sie {deploymentId} durch die Bereitstellungs-ID für Ihr neuronales Stimmmodell.

Region Training Bereitstellung Endpunkt
Australien (Osten) Ja Ja https://australiaeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Brasilien Süd Nein Ja https://brazilsouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Kanada, Mitte Nein Ja https://canadacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
USA (Mitte) Nein Ja https://centralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Asien, Osten Nein Ja https://eastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
East US Ja Ja https://eastus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
USA (Ost) 2 Ja Ja https://eastus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Frankreich, Mitte Nein Ja https://francecentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Deutschland, Westen-Mitte Nein Ja https://germanywestcentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Indien, Mitte Ja Ja https://centralindia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Japan, Osten Ja Ja https://japaneast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Japan, Westen Nein Ja https://japanwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Jio Indien, Westen Nein Ja https://jioindiawest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Korea, Mitte Ja Ja https://koreacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
USA Nord Mitte Nein Ja https://northcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Nordeuropa Ja Ja https://northeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Norwegen, Osten Nein Ja https://norwayeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Südafrika, Norden Nein Ja https://southafricanorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
USA Süd Mitte Ja Ja https://southcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Asien, Südosten Ja Ja https://southeastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Schweiz, Norden Nein Ja https://switzerlandnorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Schweiz, Westen Nein Ja https://switzerlandwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Vereinigte Arabische Emirate, Norden Nein Ja https://uaenorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
UK, Süden Ja Ja https://uksouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
USA, Westen-Mitte Nein Ja https://westcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
Europa, Westen Ja Ja https://westeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
USA (Westen) Ja Ja https://westus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
USA, Westen 2 Ja Ja https://westus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}
USA, Westen 3 Nein Ja https://westus3.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId}

Hinweis

Die oben genannten Regionen sind für das Hosting neuronaler Stimmmodelle und die Echtzeitsynthese verfügbar. Das benutzerdefinierte neuronale Stimmtraining ist nur in einigen Regionen verfügbar. Benutzer können jedoch problemlos ein neuronales Stimmmodell aus diesen Regionen in andere Regionen aus der vorherigen Liste kopieren.

API für lange Audioinhalte

Die API für lange Audioinhalte ist in mehreren Regionen mit eindeutigen Endpunkten verfügbar:

Region Endpunkt
Australien (Osten) https://australiaeast.customvoice.api.speech.microsoft.com
East US https://eastus.customvoice.api.speech.microsoft.com
Indien, Mitte https://centralindia.customvoice.api.speech.microsoft.com
USA Süd Mitte https://southcentralus.customvoice.api.speech.microsoft.com
Asien, Südosten https://southeastasia.customvoice.api.speech.microsoft.com
UK, Süden https://uksouth.customvoice.api.speech.microsoft.com
Europa, Westen https://westeurope.customvoice.api.speech.microsoft.com

Anforderungsheader

Diese Tabelle führt die erforderlichen und optionalen Header für Sprachsynthese-Anforderungen auf:

Header BESCHREIBUNG Erforderlich oder optional
Authorization Ein Autorisierungstoken, dem das Wort Bearer vorangestellt ist. Weitere Informationen finden Sie unter Authentifizierung. Erforderlich
Content-Type Gibt den Inhaltstyp des angegebenen Texts an. Zulässiger Wert: application/ssml+xml. Erforderlich
X-Microsoft-OutputFormat Gibt das Audioausgabeformat an. Eine vollständige Liste der zulässigen Werte finden Sie unter Audioausgaben. Erforderlich
User-Agent Der Anwendungsname. Der angegebene Wert darf höchstens 255 Zeichen lang sein. Erforderlich

Anforderungstext

Wenn Sie eine benutzerdefinierte neuronale Stimme verwenden, kann der Text der Anforderung als Nur-Text (ASCII oder UTF-8) gesendet werden. Andernfalls wird der Text jeder POST-Anforderung als SSML versendet. Mit SSML können Sie die Stimme und Sprache der synthetisierten Sprachausgabe auszuwählen, die vom Sprachsynthese-Feature zurückgegeben wird. Eine vollständige Liste der unterstützten Stimmen finden Sie unter Sprach- und Stimmunterstützung für den Speech-Dienst.

Beispiel für eine Anforderung

Diese HTTP-Anforderung gibt mit SSML die Stimme und die Sprache an. Wenn der Text lang ist und die resultierende Audiodatei zehn Minuten überschreitet, wird sie auf zehn Minuten gekürzt. Das heißt, die Audiodatei darf nicht länger als zehn Minuten sein.

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>

* Für die Inhaltslänge sollten Sie Ihr eigene Inhaltslänge verwenden. In den meisten Fällen wird dieser Wert automatisch berechnet.

HTTP-Statuscodes

Der HTTP-Statuscode jeder Antwort zeigt den Erfolg oder allgemeine Fehler an:

HTTP-Statuscode BESCHREIBUNG Mögliche Ursache
200 OK Die Anforderung wurde erfolgreich gesendet. Der Antwortkörper ist eine Audiodatei.
400 Ungültige Anforderung Ein erforderlicher Parameter fehlt, ist leer oder Null. Oder der an einen erforderlichen oder optionalen Parameter übergebene Wert ist ungültig. Ein häufiger Grund ist ein zu langer Header.
401 Nicht autorisiert Die Anforderung ist nicht autorisiert. Vergewissern Sie sich, dass Ihr Speech-Ressourcenschlüssel oder Token gültig ist und sich in der richtigen Region befindet.
415 Unsupported Media Type. (Nicht unterstützter Medientyp.) Möglicherweise wurde der falsche Content-Type-Wert bereitgestellt. Content-Type sollte auf application/ssml+xml festgelegt sein.
429 Zu viele Anforderungen Sie haben das Kontingent oder die Rate der für Ihre Ressource zulässigen Anforderungen überschritten.
502 Ungültiger Gateway Es liegt ein Netzwerkproblem oder serverseitiges Problem vor. Dieser Status kann auch auf ungültige Header hinweisen.

Wenn der HTTP-Status 200 OK ist, enthält der Text der Antwort eine Audiodatei im angeforderten Format. Diese Datei kann bei der Übertragung abgespielt sowie in einem Puffer oder in einer Datei gespeichert werden.

Audioausgaben

Die unterstützten Streaming- und Nichtstreaming-Audioformate werden in jeder Anforderung als X-Microsoft-OutputFormat Header gesendet. Jedes Format enthält eine Bitrate und einen Codierungstyp. Der Speech-Dienst unterstützt Audioausgaben mit 48 kHz, 24 kHz, 16 kHz und 8 kHz. Jedes vordefinierte neuronale Sprachmodell ist mit 24 kHz und als High-Fidelity-Version mit 48 kHz verfügbar.

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

Hinweis

Wenn Sie das Ausgabeformat 48 kHz auswählen, wird entsprechend das High-Fidelity-Sprachmodell mit 48 kHz aufgerufen. Andere Sampleraten als 24 kHz und 48 kHz können durch Upsampling oder Downsampling bei der Synthese erhalten werden. So wird etwa 44,1 kHz von 48 kHz heruntergesampelt.

Wenn die ausgewählte Stimme und das ausgewählte Ausgabeformat unterschiedliche Bitraten aufweisen, wird das Audio nach Bedarf neu gesampelt. Sie können das ogg-24khz-16bit-mono-opus-Format mithilfe des Opus-Codec decodieren.

Authentication

Jede Anforderung erfordert einen Autorisierungsheader. In dieser Tabelle wird veranschaulicht, welche Header für die einzelnen Features unterstützt werden:

Unterstützter Autorisierungsheader Spracherkennung Text-to-Speech
Ocp-Apim-Subscription-Key Ja Ja
Authorization: Bearer Ja Ja

Wenn Sie den Ocp-Apim-Subscription-Key Header verwenden, muss nur Ihr Ressourcenschlüssel bereitgestellt werden. Zum Beispiel:

'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'

Wenn Sie den Authorization: Bearer Header verwenden, müssen Sie eine Anforderung an den issueToken Endpunkt senden. In dieser Anforderung tauschen Sie Ihren Ressourcenschlüssel gegen ein Zugriffstoken, das 10 Minuten lang gültig ist.

Eine weitere Möglichkeit besteht darin, die Microsoft Entra-Authentifizierung zu verwenden, die auch den Authorization: Bearer Header verwendet, aber mit einem Token, das über die Microsoft Entra-ID ausgestellt wurde. Siehe Verwenden der Microsoft Entra-Authentifizierung.

Abrufen eines Zugriffstokens

Zum Abrufen eines Zugriffstokens müssen Sie eine Anforderung an den issueToken-Endpunkt mit dem Header Ocp-Apim-Subscription-Key und Ihrem Ressourcenschlüssel senden.

Der issueToken-Endpunkt hat folgendes Format:

https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken

Ersetzen Sie <REGION_IDENTIFIER> durch den Bezeichner, der mit der Region Ihres Abonnements übereinstimmt:

Verwenden Sie die folgenden Beispiele, um Ihre Zugriffstokenanforderung zu erstellen.

HTTP-Beispiel

Dieses Beispiel stellt eine einfache HTTP-Anforderung zum Abrufen eines Tokens dar. Ersetzen Sie YOUR_SUBSCRIPTION_KEY durch Ihren Ressourcenschlüssel für den Speech-Dienst. Wenn sich Ihr Abonnement nicht in der Region „USA, Westen“ befindet, ersetzen Sie den Host-Header durch den Hostnamen für Ihre Region.

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

Der Antworttext enthält das Zugriffstoken im JWT-Format (JSON Web Token).

PowerShell-Beispiel

Dieses Beispiel stellt ein einfaches PowerShell-Skript zum Abrufen eines Zugriffstokens dar. Ersetzen Sie YOUR_SUBSCRIPTION_KEY durch Ihren Ressourcenschlüssel für den Speech-Dienst. Achten Sie darauf, dass Sie den richtigen Endpunkt für die Region Ihres Abonnements verwenden. In diesem Beispiel ist das „USA, Westen“.

$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-Beispiel

cURL ist ein Befehlszeilentool, das in Linux (und im Windows-Subsystem für Linux) zur Verfügung steht. Dieser cURL-Befehl veranschaulicht, wie Sie ein Zugriffstoken abrufen. Ersetzen Sie YOUR_SUBSCRIPTION_KEY durch Ihren Ressourcenschlüssel für den Speech-Dienst. Achten Sie darauf, dass Sie den richtigen Endpunkt für die Region Ihres Abonnements verwenden. In diesem Beispiel ist das „USA, Westen“.

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#-Beispiel

Diese C#-Klasse veranschaulicht, wie Sie ein Zugriffstoken abrufen. Übergeben Sie Ihren Ressourcenschlüssel für den Speech-Dienst beim Instanziieren der Klasse. Wenn Ihr Abonnement sich nicht in der Region „USA, Westen“ befindet, ändern Sie den Wert von FetchTokenUri so, dass er der Region Ihres Abonnements entspricht.

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-Beispiel

# 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)

Verwenden eines Zugriffstokens

Das Zugriffstoken sollte als Authorization: Bearer <TOKEN>-Header an den Dienst gesendet werden. Jedes Zugriffstoken ist 10 Minuten lang gültig. Sie können jederzeit ein neues Token abrufen, allerdings wird empfohlen, das gleiche Token neun Minuten lang zu verwenden, um den Datenverkehr und die Wartezeit zu minimieren.

Hier finden Sie eine HTTP-Beispielanforderung an die Spracherkennung-REST-API für kurze Audiodaten:

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...

Verwenden der Microsoft Entra-Authentifizierung

Um die Microsoft Entra-Authentifizierung mit der Sprachausgabe-REST-API für kurze Audiodaten zu verwenden, müssen Sie ein Zugriffstoken erstellen. Die Schritte zum Abrufen des Zugriffstokens, das aus Ressourcen-ID und Microsoft Entra-Zugriffstoken besteht, sind identisch mit der Verwendung des Speech SDK. Gehen Sie folgendermaßen vor : Verwenden der Microsoft Entra-Authentifizierung

  • Erstellen einer Speech-Ressource
  • Konfigurieren der Speech-Ressource für die Microsoft Entra-Authentifizierung
  • Erhalten eines Microsoft Entra-Zugriffstokens
  • Erhalten der Sprachressourcen-ID

Nachdem die Ressourcen-ID und das Microsoft Entra-Zugriffstoken abgerufen wurden, kann das tatsächliche Zugriffstoken nach diesem Format erstellt werden:

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Sie müssen das Präfix "aad#" und das Trennzeichen "#" (Hash) zwischen Ressourcen-ID und dem Zugriffstoken einschließen.

Hier finden Sie eine HTTP-Beispielanforderung an die Spracherkennung-REST-API für kurze Audiodaten:

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...

Weitere Informationen zu Microsoft Entra-Zugriffstoken, einschließlich der Tokenlebensdauer, finden Sie unter Microsoft Identity Platform – Zugriffstoken.

Nächste Schritte