Verwenden Sie die Sprach-zu-Text REST-API für kurze Audiodateien

Verwenden Sie die Sprachausgabe-REST-API nur für kurze Audiodaten in Fällen, in denen Sie das Speech SDK oder die API für schnelle Transkription nicht verwenden können.

Bevor Sie die Spracherkennung für TEXT-REST-API für kurze Audiodaten verwenden, sollten Sie die folgenden Einschränkungen berücksichtigen:

Anforderungen, die die REST-API für kurze Audiodaten verwenden und Audio direkt übertragen, können maximal 60 Sekunden Audio enthalten. Bei der Aussprachebewertung sollte die Audiodauer nicht mehr als 30 Sekunden betragen. Die Eingabeaudioformate sind im Vergleich zum Speech SDK eingeschränkter.
Die REST-API für kurze Audiodaten gibt nur endgültige Ergebnisse zurück. Es werden keine Teilergebnisse bereitgestellt.
Die Sprachübersetzung wird nicht über die REST-API für kurze Audiodaten unterstützt. Sie müssen das Speech SDK verwenden.
Batchtranskription und benutzerdefinierte Spracherkennung werden nicht über die REST-API für kurze Audiodaten unterstützt. Sie sollten immer die Speech to Text REST-API für Batch-Transkription und benutzerdefinierte Sprache verwenden.

Bevor Sie die Spracherkennung für TEXT-REST-API für kurze Audiodaten verwenden, sollten Sie wissen, dass Sie einen Tokenaustausch als Teil der Authentifizierung abschließen müssen, um auf den Dienst zuzugreifen. Weitere Informationen finden Sie unter "Authentifizierung".

Regionen und Endpunkte

Der Endpunkt für die REST-API für kurze Audiodaten weist dieses Format auf:

https://YourResourceName.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1

Ersetzen Sie YourResourceName durch den Namen Ihrer Sprachressource.

Hinweis

Informationen zu Azure Government- und Microsoft Azure-Endpunkten, betrieben von 21Vianet, finden Sie in diesem Artikel zu Sovereign Clouds.

Audioformate

Audio wird im Textkörper der HTTP-Anforderung POST gesendet. Es muss sich in einem der Formate in dieser Tabelle befinden:

Format	Codec	Bitrate	Samplingrate
WAV	PCM	256 kbit/s	16 kHz, Mono
OGG	OPUS	256 kbit/s	16 kHz, Mono

Hinweis

Die vorstehenden Formate werden über die REST-API für kurze Audio- und WebSockets im Sprachdienst unterstützt. Das Speech SDK unterstützt das WAV-Format mit PCM-Codec sowie andere Formate.

Anforderungsheader

In dieser Tabelle sind die erforderlichen und optionalen Kopfzeilen für Spracher-zu-Text-Anfragen aufgeführt.

Kopfzeile	Beschreibung	Erforderlich oder optional
`Ocp-Apim-Subscription-Key`	Der Ressourcenschlüssel für den Sprachdienst.	Entweder diese Kopfzeile oder `Authorization` ist erforderlich.
`Authorization`	Ein Autorisierungstoken vor dem Wort `Bearer`. Weitere Informationen finden Sie unter "Authentifizierung".	Entweder diese Kopfzeile oder `Ocp-Apim-Subscription-Key` ist erforderlich.
`Pronunciation-Assessment`	Gibt die Parameter zum Anzeigen von Ausspracheergebnissen in Erkennungsergebnissen an. Diese Bewertungen bewerten die Aussprachequalität der Spracheingabe mit Indikatoren wie Genauigkeit, Fluktat und Vollständigkeit. Dieser Parameter ist ein base64-codierter JSON-Code, der mehrere detaillierte Parameter enthält. Informationen dazu, wie dieser Header aufgebaut wird, finden Sie unter Bewertungsparameter zur Aussprache.	Optional
`Content-type`	Beschreibt das Format und den Codec der bereitgestellten Audiodaten. Akzeptierte Werte sind `audio/wav; codecs=audio/pcm; samplerate=16000` und `audio/ogg; codecs=opus`.	Erforderlich
`Transfer-Encoding`	Gibt an, dass gestückelte Audiodaten statt einer einzelnen Datei übertragen werden. Verwenden Sie diesen Header nur, wenn Sie Audiodaten blöcken.	Optional
`Expect`	Wenn Sie segmentierte Übertragung verwenden, senden Sie `Expect: 100-continue`. Der Sprachdienst erkennt die anfängliche Anforderung an und wartet auf weitere Daten.	Erforderlich, wenn Sie in Segmente unterteilte Audiodaten senden.
`Accept`	Wenn angegeben, muss es sein `application/json`. Der Sprachdienst stellt Ergebnisse in JSON bereit. Einige Anforderungsframeworks stellen einen inkompatiblen Standardwert bereit. Es ist ratsam, `Accept` immer einzuschließen.	Optional, aber empfohlen.

Abfrageparameter

Diese Parameter können in der Abfragezeichenfolge der REST-Anforderung enthalten sein.

Hinweis

Sie müssen den Sprachparameter an die URL anfügen, um den Empfang eines 4xx-HTTP-Fehlers zu vermeiden. Beispielsweise ist als Spracheinstellung US-Englisch festgelegt: https://YourResourceName.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Parameter	Beschreibung	Erforderlich oder optional
`language`	Identifiziert die gesprochene Sprache, die erkannt wird. Siehe unterstützte Sprachen.	Erforderlich
`format`	Gibt das Ergebnisformat an. Akzeptierte Werte sind `simple` und `detailed`. Einfache Ergebnisse umfassen `RecognitionStatus`, , `DisplayText`, `Offset`und `Duration`. Detaillierte Antworten umfassen vier verschiedene Darstellungen von Anzeigetext. Die Standardeinstellung ist `simple`.	Optional
`profanity`	Gibt an, wie Profanität in Erkennungsergebnissen behandelt wird. Akzeptierte Werte sind: `masked`, die Profanität durch Sternchen ersetzt. `removed`, wodurch alle Profanität aus dem Ergebnis entfernt wird. `raw`, das Profanität im Ergebnis enthält. Die Standardeinstellung ist `masked`.	Optional

Bewertungsparameter für die Aussprache

In dieser Tabelle sind die erforderlichen und optionalen Parameter für die Aussprachebewertung aufgeführt:

Parameter	Beschreibung	Erforderlich oder optional
`ReferenceText`	Der Text, für den die Aussprache ausgewertet wird.	Erforderlich
`GradingSystem`	Das Punktsystem für die Bewertungskalibrierung. Das `FivePoint` System gibt eine 0-5 Gleitkommabewertung und `HundredMark` gibt eine 0-100 Gleitkommabewertung. Standard: `FivePoint`.	Optional
`Granularity`	Die Granularität der Auswertung. Akzeptierte Werte sind: `Phoneme`, in dem die Bewertung auf den Ebenen "Volltext", "Wort" und "Phoneme" angezeigt wird. `Word`, das die Bewertung auf der Volltext- und Wortebene zeigt. `FullText`, der die Bewertung nur auf der Volltextebene anzeigt. Die Standardeinstellung ist `Phoneme`.	Optional
`Dimension`	Definiert die Ausgabekriterien. Akzeptierte Werte sind: `Basic`, die nur die Genauigkeitsbewertung anzeigt. `Comprehensive`, die Bewertungen für weitere Dimensionen anzeigt (z. B. Fluency Score und Vollständigkeitsbewertung auf der Volltextebene und Fehlertyp auf der Wortebene). Informationen zum Anzeigen von Definitionen verschiedener Bewertungsdimensionen und Wortfehlertypen finden Sie unter Antworteigenschaften. Die Standardeinstellung ist `Basic`.	Optional
`EnableMiscue`	Aktiviert die Fehlschlagsberechnung. Wenn dieser Parameter aktiviert ist, werden die ausgesprochenen Wörter mit dem Bezugstext verglichen. Sie werden basierend auf dem Vergleich mit Auslassung oder Einfügung gekennzeichnet. Akzeptierte Werte sind `False` und `True`. Die Standardeinstellung ist `False`.	Optional
`EnableProsodyAssessment`	Ermöglicht die Prosodybewertung für Ihre Ausspracheauswertung. Diese Funktion bewertet Aspekte wie Stress, Intonation, Sprachgeschwindigkeit und Rhythmus. Dieses Feature bietet Einblicke in die Natürlichkeit und Ausdrucksfähigkeit Ihrer Rede. Wenn diese Eigenschaft auf `True` gesetzt ist, wird der `ProsodyScore` Ergebniswert zurückgegeben.	Optional
`ScenarioId`	Eine GUID, die ein angepasstes Punktsystem angibt.	Optional

Hier sehen Sie ein Beispiel-JSON, das die Parameter für die Aussprachebewertung enthält:

{
  "ReferenceText": "Good morning.",
  "GradingSystem": "HundredMark",
  "Granularity": "Word",
  "Dimension": "Comprehensive",
  "EnableProsodyAssessment": "True"
}

Der folgende Beispielcode zeigt, wie die Parameter für die Aussprachebewertung in den Pronunciation-Assessment Header erstellt werden:

var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"Word\",\"Dimension\":\"Comprehensive\",\"EnableProsodyAssessment\":\"True\"}}";
var pronAssessmentParamsBytes = Encoding.UTF8.GetBytes(pronAssessmentParamsJson);
var pronAssessmentHeader = Convert.ToBase64String(pronAssessmentParamsBytes);

Es wird dringend empfohlen, die Audiodaten als Streaming-Upload (Chunked Transfer) zu veröffentlichen, wodurch die Latenz erheblich reduziert werden kann. Informationen zum Aktivieren des Streamings finden Sie im Beispielcode in verschiedenen Programmiersprachen.

Hinweis

Weitere Informationen finden Sie unter Aussprachebewertung.

Beispielanforderung

Das folgende Beispiel enthält den Hostnamen und die erforderlichen Header. Es ist wichtig zu beachten, dass der Dienst auch Audiodaten erwartet, die in diesem Beispiel nicht enthalten sind. Wie bereits erwähnt, wird die Segmentierung empfohlen, ist aber nicht erforderlich.

POST speech/recognition/conversation/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codecs=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Host: YourResourceName.cognitiveservices.azure.com
Transfer-Encoding: chunked
Expect: 100-continue

Um die Aussprachebewertung zu aktivieren, können Sie den folgenden Header hinzufügen. Informationen dazu, wie dieser Header aufgebaut wird, finden Sie unter Bewertungsparameter zur Aussprache.

Pronunciation-Assessment: eyJSZWZlcm...

HTTP-Statuscodes

Der HTTP-Statuscode für jede Antwort weist auf Erfolg oder häufige Fehler hin.

HTTP-Statuscode	Beschreibung	Mögliche Gründe
100	Weiter	Die ursprüngliche Anforderung wird akzeptiert. Fahren Sie mit dem Senden der restlichen Daten fort. (Dieser Code wird mit Übertragung in Blöcken verwendet.)
200	OKAY	Die Anforderung war erfolgreich. Der Antwortkörper ist ein JSON-Objekt.
400	Ungültige Anforderung	Der Sprachcode wurde nicht angegeben, die Sprache wird nicht unterstützt, oder die Audiodatei ist ungültig (z. B.).
401	Unbefugt	Ein Ressourcenschlüssel oder ein Autorisierungstoken ist in der angegebenen Region ungültig, oder ein Endpunkt ist ungültig.
403	Verboten	Ein Ressourcenschlüssel oder Autorisierungstoken fehlt.

Beispielantworten

Hier ist eine typische Antwort für simple-Erkennung:

{
  "RecognitionStatus": "Success",
  "DisplayText": "Remind me to buy 5 pencils.",
  "Offset": "1236645672289",
  "Duration": "1236645672289"
}

Hier ist eine typische Antwort für detailed-Erkennung:

{
  "RecognitionStatus": "Success",
  "Offset": "1236645672289",
  "Duration": "1236645672289",
  "NBest": [
    {
      "Confidence": 0.9052885,
      "Display": "What's the weather like?",
      "ITN": "what's the weather like",
      "Lexical": "what's the weather like",
      "MaskedITN": "what's the weather like"
    },
    {
      "Confidence": 0.92459863,
      "Display": "what is the weather like",
      "ITN": "what is the weather like",
      "Lexical": "what is the weather like",
      "MaskedITN": "what is the weather like"
    }
  ]
}

Hier ist eine typische Antwort für die Erkennung mit Aussprachebewertung:

{
  "RecognitionStatus": "Success",
  "Offset": 700000,
  "Duration": 8400000,
  "DisplayText": "Good morning.",
  "SNR": 38.76819,
  "NBest": [
    {
      "Confidence": 0.98503506,
      "Lexical": "good morning",
      "ITN": "good morning",
      "MaskedITN": "good morning",
      "Display": "Good morning.",
      "AccuracyScore": 100.0,
      "FluencyScore": 100.0,
      "ProsodyScore": 87.8,
      "CompletenessScore": 100.0,
      "PronScore": 95.1,
      "Words": [
        {
          "Word": "good",
          "Offset": 700000,
          "Duration": 2600000,
          "Confidence": 0.0,
          "AccuracyScore": 100.0,
          "ErrorType": "None",
          "Feedback": {
            "Prosody": {
              "Break": {
                "ErrorTypes": [
                  "None"
                ],
                "BreakLength": 0
              },
              "Intonation": {
                "ErrorTypes": [],
                "Monotone": {
                  "Confidence": 0.0,
                  "WordPitchSlopeConfidence": 0.0,
                  "SyllablePitchDeltaConfidence": 0.91385907
                }
              }
            }
          }
        },
        {
          "Word": "morning",
          "Offset": 3400000,
          "Duration": 5700000,
          "Confidence": 0.0,
          "AccuracyScore": 100.0,
          "ErrorType": "None",
          "Feedback": {
            "Prosody": {
              "Break": {
                "ErrorTypes": [
                  "None"
                ],
                "UnexpectedBreak": {
                  "Confidence": 3.5294118e-08
                },
                "MissingBreak": {
                  "Confidence": 1.0
                },
                "BreakLength": 0
              },
              "Intonation": {
                "ErrorTypes": [],
                "Monotone": {
                  "Confidence": 0.0,
                  "WordPitchSlopeConfidence": 0.0,
                  "SyllablePitchDeltaConfidence": 0.91385907
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Antworteigenschaften

Ergebnisse werden als JSON bereitgestellt. Das simple Format enthält die folgenden Felder auf oberster Ebene:

Eigenschaft	Beschreibung
`RecognitionStatus`	Status, wie `Success` für eine erfolgreiche Erkennung. Weitere Informationen finden Sie in der nächsten Tabelle.
`DisplayText`	Der erkannte Text nach Groß- und Kleinschreibung, Interpunktion, umgekehrter Textnormalisierung und Profanitätsmaske. Nur bei Erfolg präsentieren. Inverse Textnormalisierung ist die Konvertierung von gesprochenem Text in kürzere Formen, z. B. 200 für „zweihundert“ oder „Dr. Schmidt“ für „Doktor Schmidt“.
`Offset`	Die Zeit (in 100 Nanosekunden), zu der die erkannte Sprache im Audiodatenstrom beginnt.
`Duration`	Die Dauer (in 100 Nanosekundeneinheiten) der erkannten Sprache im Audiodatenstrom.
`SNR`	Das Signal-zu-Rausch-Verhältnis (SNR) der erkannten Sprache im Audiodatenstrom.

Das RecognitionStatus Feld kann die folgenden Werte enthalten:

Status	Beschreibung
`Success`	Die Erkennung war erfolgreich, und das `DisplayText` Feld ist vorhanden.
`NoMatch`	Sprache wurde im Audiodatenstrom erkannt, aber es wurden keine Wörter aus der Zielsprache gefunden. Dieser Status bedeutet in der Regel, dass sich die Spracherkennung von der Sprache unterscheidet, die der Benutzer spricht.
`InitialSilenceTimeout`	Der Anfang des Audiodatenstroms enthielt nur Stille, und beim Warten auf Sprache wurde das Timeout des Diensts aktiviert.
`BabbleTimeout`	Der Anfang des Audiodatenstroms enthielt nur Rauschen, und beim Warten auf Sprache wurde das Timeout des Diensts aktiviert.
`Error`	Der Erkennungsdienst hat einen internen Fehler festgestellt und konnte nicht fortgesetzt werden. Versuchen Sie es nach Möglichkeit erneut.

Hinweis

Wenn das Audio nur aus Profanität besteht und der profanity Abfrageparameter auf remove festgelegt ist, gibt der Dienst kein Sprachergebnis zurück.

Das detailed Format enthält weitere Formen erkannter Ergebnisse. Wenn Sie das detailed-Format verwenden, wird DisplayText als Display für jedes Ergebnis in der NBest-Liste angegeben.

Das Objekt in der NBest Liste kann Folgendes enthalten:

Eigenschaft	Beschreibung
`Confidence`	Die Konfidenzbewertung des Eintrags von 0,0 (keine Konfidenz) bis 1,0 (volle Konfidenz).
`Lexical`	Die lexikalische Form des erkannten Texts: die tatsächlich erkannten Wörter.
`ITN`	Die inverse Textnormalisierung (ITN) oder kanonische Form des erkannten Texts nach der Anwendung von Telefonnummern, Zahlen, Abkürzungen („Doktor Schmidt“ zu „Dr. Schmidt“) und weiteren Transformationen.
`MaskedITN`	Das ITN-Formular mit angewendeter Maskierung von anstößiger Sprache, falls angefordert.
`Display`	Die Anzeigeform des erkannten Texts mit hinzugefügter Interpunktion und Groß-/Kleinschreibung. Dieser Parameter ist identisch mit dem, was `DisplayText` beim Festlegen des Formats auf `simple`.
`AccuracyScore`	Aussprachegenauigkeit der Sprache. Genauigkeit gibt an, wie genau die Phoneme mit der Aussprache eines Muttersprachlers übereinstimmen. Die Genauigkeitsbewertung auf den Wort- und Volltextebenen wird anhand der Genauigkeitsbewertung auf Phoneme-Ebene aggregiert.
`FluencyScore`	Flüssigkeit der bereitgestellten Sprache. Der Redefluss bedeutet, wie exakt der ausgegebene Text mit den Pausen zwischen Wörtern eines Muttersprachlers übereinstimmt.
`ProsodyScore`	Die Prosodie der gegebenen Rede. Die Prosodie gibt an, wie natürlich die gegebene Sprache ist, einschließlich Betonung, Intonation, Sprechgeschwindigkeit und Rhythmus. Informationen zu Definitionen der Ergebnisse der prosody-Bewertung finden Sie unter "Ergebnisparameter".
`CompletenessScore`	Vollständigkeit der Sprache, bestimmt durch das Berechnen des Verhältnisses der ausgesprochenen Wörter zur Referenztexteingabe.
`PronScore`	Gesamtbewertung, die die Aussprachequalität der bereitgestellten Sprache angibt. Diese Bewertung wird aus `AccuracyScore`, `FluencyScore`und `CompletenessScore` mit Gewichtung aggregiert.
`ErrorType`	Wert, der angibt, ob ein Wort im Vergleich zu `ReferenceText` weggelassen, eingefügt oder schlecht ausgesprochen wird. Mögliche Werte sind `None` (d. h. kein Fehler in diesem Wort), `Omission`, `Insertion`, und `Mispronunciation`.

Übertragung in Blöcken

Mithilfe der segmentierten Übertragung (Transfer-Encoding: chunked) kann die Erkennungslatenz verringert werden. Er ermöglicht es dem Sprachdienst, mit der Verarbeitung der Audiodatei zu beginnen, während sie übertragen wird. Die REST-API für kurze Audiodaten bietet keine Teil- oder Zwischenergebnisse.

Das folgende Codebeispiel zeigt, wie Audio in Blöcken gesendet wird. Nur der erste Block sollte den Header der Audiodatei enthalten. request ist ein HttpWebRequest Objekt, das mit dem entsprechenden REST-Endpunkt verbunden ist. audioFile ist der Pfad zu einer Audiodatei auf dem Datenträger.

var request = (HttpWebRequest)HttpWebRequest.Create(requestUri);
request.SendChunked = true;
request.Accept = @"application/json;text/xml";
request.Method = "POST";
request.ProtocolVersion = HttpVersion.Version11;
request.Host = host;
request.ContentType = @"audio/wav; codecs=audio/pcm; samplerate=16000";
request.Headers["Ocp-Apim-Subscription-Key"] = "YOUR_RESOURCE_KEY";
request.AllowWriteStreamBuffering = false;

using (var fs = new FileStream(audioFile, FileMode.Open, FileAccess.Read))
{
    // Open a request stream and write 1,024-byte chunks in the stream one at a time.
    byte[] buffer = null;
    int bytesRead = 0;
    using (var requestStream = request.GetRequestStream())
    {
        // Read 1,024 raw bytes from the input audio file.
        buffer = new Byte[checked((uint)Math.Min(1024, (int)fs.Length))];
        while ((bytesRead = fs.Read(buffer, 0, buffer.Length)) != 0)
        {
            requestStream.Write(buffer, 0, bytesRead);
        }

        requestStream.Flush();
    }
}

Authentifizierung

Jede Anforderung erfordert einen Autorisierungsheader. In dieser Tabelle wird veranschaulicht, welche Kopfzeilen für jedes Feature unterstützt werden:

Unterstützter Autorisierungsheader	Sprach-zu-Text-Erkennung	Text-zu-Sprache
`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': 'YourSpeechResourceKey'

Wenn Sie den STS-Bearer-Token-Fluss mit Authorization: Bearerverwenden, stellen Sie zuerst eine Anforderung an den issueToken Endpunkt. In dieser Anforderung tauschen Sie Ihren Ressourcenschlüssel für ein Zugriffstoken aus, das 10 Minuten gültig ist.

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

So erhalten Sie ein STS-Zugriffstoken

Um ein STS-Zugriffstoken zu erhalten, senden Sie unter Verwendung von Ocp-Apim-Subscription-Key und Ihrem Ressourcenschlüssel eine Anforderung an den Endpunkt issueToken.

Der issueToken Endpunkt hat dieses Format:

https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken

Ersetzen Sie YourResourceName durch den Namen Ihrer Sprachressource.

Hinweis

Für diesen Endpunkt muss Ihre Ressource eine benutzerdefinierte Unterdomäne konfiguriert haben. Verwenden Sie für Ressourcen ohne benutzerdefinierte Domäne stattdessen den regionalen Endpunkt: https://<region>.api.cognitive.microsoft.com/sts/v1.0/issueToken. Ersetzen Sie <region> durch die Azure Region Ihrer Ressource (z. B. eastus).

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

HTTP-Beispiel

Dieses Beispiel ist eine einfache HTTP-Anforderung zum Abrufen eines Tokens. Ersetzen Sie YourSpeechResourceKey durch Ihren Ressourcenschlüssel für den Sprachdienst. Ersetzen Sie YourResourceName durch den Namen Ihrer Sprachressource.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YourSpeechResourceKey
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0

Der Textkörper der Antwort enthält das Zugriffstoken im JWT-Format (JSON Web Token).

PowerShell-Beispiel

Dieses Beispiel ist ein einfaches PowerShell-Skript zum Abrufen eines Zugriffstokens. Ersetzen Sie YourSpeechResourceKey durch Ihren Ressourcenschlüssel für den Sprachdienst. Ersetzen Sie YourResourceName durch den Namen Ihrer Sprachressource.

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YourSpeechResourceKey'
}

$OAuthToken = Invoke-RestMethod -Method POST `
    -Uri https://YourResourceName.cognitiveservices.azure.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) verfügbar ist. Dieser cURL-Befehl veranschaulicht das Abrufen eines Zugriffstokens. Ersetzen Sie YourSpeechResourceKey durch Ihren Ressourcenschlüssel für den Sprachdienst. Ersetzen Sie YourResourceName durch den Namen Ihrer Sprachressource.

curl -v -X POST \
 "https://YourResourceName.cognitiveservices.azure.com/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey"

C#-Beispiel

Diese C#-Klasse veranschaulicht, wie sie ein Zugriffstoken abrufen. Übergeben Sie den Ressourcenschlüssel für den Sprachdienst, wenn Sie die Klasse instanziieren. Ersetzen Sie YourResourceName durch den Namen Ihrer Sprachressource.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://YourResourceName.cognitiveservices.azure.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();
        }
    }
}

beispiel für Python

# 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://YourResourceName.cognitiveservices.azure.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)

So verwenden Sie ein Zugriffstoken.

Das Zugriffstoken sollte als Header an den Authorization: Bearer <TOKEN> Dienst gesendet werden. Jedes Zugriffstoken ist 10 Minuten gültig. Sie können jederzeit ein neues Token abrufen, aber um den Netzwerkdatenverkehr und die Latenz zu minimieren, empfehlen wir die Verwendung desselben Tokens für neun Minuten.

Important

Bearer-Token sind auf den Endpunkt beschränkt, der sie ausgestellt hat. Ein von YourResourceName.cognitiveservices.azure.com abgerufenes Token funktioniert nur für Anfragen an denselben Host. Ein Token von <region>.api.cognitive.microsoft.com funktioniert nur mit regionalen Speech-Endpunkten. Wenn Sie bei der Verwendung eines Bearer-Tokens einen 401-Fehler erhalten, verwenden Sie stattdessen Ocp-Apim-Subscription-Key mit Ihrem Ressourcenschlüssel, was mit allen Endpunktformaten funktioniert.

Hier ist eine Beispiel-HTTP-Anforderung an die SPRACH-ZU-Text-REST-API für kurze Audiodaten:

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: YourResourceName.cognitiveservices.azure.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

Verwenden Sie die Microsoft Entra-Authentifizierung

Um 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. Führen Sie die hier aufgeführten Schritte Use Microsoft Entra authentication

Erstellen einer Foundry-Ressource für Sprache
Konfigurieren der Sprachressource für Microsoft Entra Authentifizierung
Rufen Sie ein Microsoft Entra Zugriffstoken ab
Abrufen der ID der Sprachressource

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 ist eine Beispiel-HTTP-Anforderung an die SPRACH-ZU-Text-REST-API für kurze Audiodaten:

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: YourResourceName.cognitiveservices.azure.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 Access-Token im Microsoft Identity Platform.

Feedback

War diese Seite hilfreich?

Last updated on 2026-05-21

Verwenden Sie die Sprach-zu-Text REST-API für kurze Audiodateien

Regionen und Endpunkte

Audioformate

Anforderungsheader

Abfrageparameter

Bewertungsparameter für die Aussprache

Beispielanforderung

HTTP-Statuscodes

Beispielantworten

Antworteigenschaften

Übertragung in Blöcken

Authentifizierung

So erhalten Sie ein STS-Zugriffstoken

HTTP-Beispiel

PowerShell-Beispiel

cURL-Beispiel

C#-Beispiel

beispiel für Python

So verwenden Sie ein Zugriffstoken.

Verwenden Sie die Microsoft Entra-Authentifizierung

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen