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.

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:

• Eine vollständige Liste der Stimmen finden Sie unter Sprach- und Stimmunterstützung für den Speech-Dienst.
• Informationen zur regionalen Verfügbarkeit finden Sie unter Vom Speech-Dienst unterstützte Regionen.
• Informationen zu Azure Government- und Microsoft Azure-Endpunkten, betrieben von 21Vianet, finden Sie in diesem Artikel zu Sovereign Clouds.

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.

Anforderungsheader

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

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.

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:

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.

API für lange Audioinhalte

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

Anforderungsheader

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

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:

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

riff-8khz-8bit-mono-alaw
riff-8khz-8bit-mono-mulaw
riff-8khz-16bit-mono-pcm
riff-22050hz-16bit-mono-pcm
riff-24khz-16bit-mono-pcm
riff-44100hz-16bit-mono-pcm
riff-48khz-16bit-mono-pcm

Authentication

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

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

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

• Erstellen Sie ein kostenloses Azure-Konto.
• Erste Schritte mit „Benutzerdefinierte neuronale Stimme“
• Batchsynthese