Spracherkennung-REST-API für kurze Audiodaten

Anwendungsfälle für die Spracherkennung-REST-API für kurze Audiodaten sind begrenzt. Verwenden Sie sie nur in Fällen, in denen Sie das Speech SDK nicht verwenden können.

Bedenken Sie die folgenden Einschränkungen, bevor Sie die Spracherkennung-REST-API für kurze Audiodaten verwenden:

• Anforderungen, die die REST-API für kurze Audiodaten verwenden und Audiodaten direkt übertragen, können nur bis zu 60 Sekunden Audiodaten enthalten. Die Eingabeaudioformate sind im Vergleich zum Speech SDK eingeschränkter.
• Die REST-API für kurze Audioinhalte gibt nur Endergebnisse zurück. Sie liefert keine Teilergebnisse.
• 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 die Spracherkennung immer zur Rest-API für Text für batchtranskription und benutzerdefinierte Spracherkennung verwenden.

Bevor Sie die Spracherkennung-REST-API für kurze Audiodaten verwenden, sollten Sie verstehen, dass Sie einen Tokenaustausch als Teil der Authentifizierung durchführen müssen, um auf den Dienst zugreifen zu können. Weitere Informationen finden Sie unter Authentifizierung.

Regionen und Endpunkte

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

https://<REGION_IDENTIFIER>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1

Ersetzen Sie <REGION_IDENTIFIER> durch den Bezeichner, der mit der Region Ihrer Speech-Ressource übereinstimmt.

Audioformate

Audiodaten werden im Text der HTTP-POST-Anforderung gesendet. Sie müssen in einem der in der folgenden Tabelle aufgeführten Formate vorliegen:

Anforderungsheader

In der folgenden Tabelle sind die erforderlichen und optionalen Header für Spracherkennungsanforderungen aufgeführt:

Abfrageparameter

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

Parameter für die Aussprachebewertung

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

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

{
  "ReferenceText": "Good morning.",
  "GradingSystem": "HundredMark",
  "Granularity": "FullText",
  "Dimension": "Comprehensive"
}

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

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

Für die Veröffentlichung von Audiodaten wird dringend das Hochladen per Streaming (segmentierter Transfer) empfohlen, da damit die Latenz deutlich reduziert werden kann. Informationen zum Aktivieren des Streamings finden Sie im Beispielcode in verschiedenen Programmiersprachen.

Beispiel für eine Anforderung

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: westus.stt.speech.microsoft.com
Transfer-Encoding: chunked
Expect: 100-continue

Sie können den folgenden Header hinzufügen, um die Aussprachebewertung zu aktivieren. Informationen zum Erstellen dieses Headers finden Sie unter Parameter für die Aussprachebewertung.

Pronunciation-Assessment: eyJSZWZlcm...

HTTP-Statuscodes

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

Beispielantworten

Hier sehen Sie eine typische Antwort für die Erkennung simple:

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

Hier sehen Sie eine typische Antwort für die Erkennung detailed:

{
  "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 sehen Sie eine typische Antwort für Erkennung mit Bewertung der Aussprache:

{
  "RecognitionStatus": "Success",
  "Offset": "400000",
  "Duration": "11000000",
  "NBest": [
      {
        "Confidence" : "0.87",
        "Lexical" : "good morning",
        "ITN" : "good morning",
        "MaskedITN" : "good morning",
        "Display" : "Good morning.",
        "PronScore" : 84.4,
        "AccuracyScore" : 100.0,
        "FluencyScore" : 74.0,
        "CompletenessScore" : 100.0,
        "Words": [
            {
              "Word" : "Good",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 500000,
              "Duration" : 2700000
            },
            {
              "Word" : "morning",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 5300000,
              "Duration" : 900000
            }
        ]
      }
  ]
}

Antworteigenschaften

Ergebnisse werden im JSON-Format bereitgestellt. Das Format simple schließt die folgenden Felder auf oberster Ebene ein:

Das RecognitionStatus-Feld kann diese Werte enthalten:

Das detailed Format enthält weitere Formen erkannter Ergebnisse. Bei Verwendung des Formats detailed wird DisplayText für jedes Ergebnis in der NBest-Liste als Display angegeben.

Das Objekt in der NBest-Liste kann Folgendes enthalten:

Segmentierte Übertragung

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

Das folgende Codebeispiel zeigt, wie Sie Audiodaten in Blöcken senden. 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();
    }
}

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

• Anpassen von Sprachmodellen
• Machen Sie sich mit Batchtranskription vertraut