Rest-API för tal till text för kort ljud

Artikel
09/23/2024

Användningsfallen för REST API för tal till text för kort ljud är begränsade. Använd den endast i fall där du inte kan använda Speech SDK.

Innan du använder REST API för tal till text för kort ljud bör du tänka på följande begränsningar:

Begäranden som använder REST-API:et för kort ljud och överför ljud direkt får inte innehålla mer än 60 sekunders ljud. Indataljudformaten är mer begränsade jämfört med Speech SDK.
REST-API:et för kort ljud returnerar endast slutliga resultat. Det ger inte partiella resultat.
Talöversättning stöds inte via REST API för kort ljud. Du måste använda Speech SDK.
Batch-transkription och anpassat tal stöds inte via REST API för kort ljud. Du bör alltid använda REST API för tal till text för batch-transkription och anpassat tal.

Innan du använder REST API för tal till text för kort ljud bör du förstå att du måste slutföra ett tokenutbyte som en del av autentiseringen för att få åtkomst till tjänsten. Mer information finns i Autentisering.

Regioner och slutpunkter

Slutpunkten för REST-API:et för kort ljud har följande format:

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

Ersätt <REGION_IDENTIFIER> med identifieraren som matchar regionen för din Speech-resurs.

Kommentar

Information om Azure Government och Microsoft Azure som drivs av 21Vianet-slutpunkter finns i den här artikeln om nationella moln.

Ljudformat

Ljud skickas i brödtexten i HTTP-begäran POST . Den måste vara i något av formaten i den här tabellen:

Format	Codec	Bithastighet	Exempelfrekvens
WAV	PCM	256 kbit/s	16 kHz, mono
OGG	OPUS	256 kbit/s	16 kHz, mono

Kommentar

Föregående format stöds via REST-API:et för kort ljud och WebSocket i Speech-tjänsten. Speech SDK har stöd för WAV-format med PCM codec och andra format.

Begärandehuvuden

Den här tabellen visar obligatoriska och valfria rubriker för tal till text-begäranden:

Header	beskrivning	Obligatorisk eller valfri
`Ocp-Apim-Subscription-Key`	Din resursnyckel för Speech-tjänsten.	Antingen den här rubriken eller `Authorization` krävs.
`Authorization`	En auktoriseringstoken föregås av ordet `Bearer`. Mer information finns i Autentisering.	Antingen den här rubriken eller `Ocp-Apim-Subscription-Key` krävs.
`Pronunciation-Assessment`	Anger parametrarna för att visa uttalspoäng i igenkänningsresultat. Dessa poäng utvärderar uttalskvaliteten för talindata, med indikatorer som noggrannhet, flyt och fullständighet. Den här parametern är en Base64-kodad JSON som innehåller flera detaljerade parametrar. Information om hur du skapar den här rubriken finns i Utvärderingsparametrar för uttal.	Valfritt
`Content-type`	Beskriver formatet och codec för angivna ljuddata. Godkända värden är `audio/wav; codecs=audio/pcm; samplerate=16000` och `audio/ogg; codecs=opus`.	Obligatoriskt
`Transfer-Encoding`	Anger att segmenterade ljuddata skickas i stället för en enda fil. Använd endast det här huvudet om du segmenterar ljuddata.	Valfritt
`Expect`	Om du använder segmenterad överföring skickar du `Expect: 100-continue`. Speech-tjänsten bekräftar den första begäran och väntar på mer data.	Krävs om du skickar segmenterade ljuddata.
`Accept`	Om det anges måste det vara `application/json`. Speech-tjänsten ger resultat i JSON. Vissa ramverk för begäran ger ett inkompatibelt standardvärde. Det är bra att alltid inkludera `Accept`.	Valfritt, men rekommenderas.

Frågeparametrar

Dessa parametrar kan ingå i frågesträngen för REST-begäran.

Kommentar

Du måste lägga till språkparametern i URL:en för att undvika att få ett 4xx HTTP-fel. Till exempel är språket som är inställt på amerikansk engelska via slutpunkten USA, västra: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Parameter	Description	Obligatorisk eller valfri
`language`	Identifierar det talade språk som identifieras. Se Språk som stöds.	Obligatoriskt
`format`	Anger resultatformatet. Godkända värden är `simple` och `detailed`. Enkla resultat är `RecognitionStatus`, `DisplayText`, `Offset`och `Duration`. Detaljerade svar innehåller fyra olika representationer av visningstext. Standardinställningen är `simple`.	Valfritt
`profanity`	Anger hur du hanterar svordomar i igenkänningsresultat. Godkända värden är: `masked`, som ersätter svordomar med asterisker. `removed`, vilket tar bort alla svordomar från resultatet. `raw`, vilket inkluderar svordomar i resultatet. Standardinställningen är `masked`.	Valfritt
`cid`	När du använder Speech Studio för att skapa anpassade modeller kan du dra nytta av värdet för slutpunkts-ID från sidan Distribution . Använd värdet för slutpunkts-ID som argument för frågesträngsparametern`cid`.	Valfritt

Utvärderingsparametrar för uttal

Den här tabellen visar obligatoriska och valfria parametrar för uttalsbedömning:

Parameter	Description	Obligatorisk eller valfri
`ReferenceText`	Texten som uttalet utvärderas mot.	Obligatoriskt
`GradingSystem`	Poängsystemet för poängkalibrering. Systemet `FivePoint` ger en 0-5 flyttal poäng och `HundredMark` ger en 0-100 flyttalspoäng. Standard: `FivePoint`.	Valfritt
`Granularity`	Utvärderingskornigheten. Godkända värden är: `Phoneme`, som visar poängen på nivåerna fulltext, ord och fonem. `Word`, som visar poängen på fulltext- och ordnivåerna. `FullText`, som endast visar poängen på fulltextnivån. Standardinställningen är `Phoneme`.	Valfritt
`Dimension`	Definierar utdatavillkoren. Godkända värden är: `Basic`, som endast visar noggrannhetspoängen. `Comprehensive`, som visar poäng på fler dimensioner (till exempel fluency score and completeness score on the full-text level, and error type on the word level). Information om definitioner av olika poängdimensioner och ordfelstyper finns i Svarsegenskaper. Standardinställningen är `Basic`.	Valfritt
`EnableMiscue`	Aktiverar felberäkning. Med den här parametern aktiverad jämförs de uttalade orden med referenstexten. De markeras med utelämnande eller insättning baserat på jämförelsen. Godkända värden är `False` och `True`. Standardinställningen är `False`.	Valfritt
`ScenarioId`	Ett GUID som anger ett anpassat punktsystem.	Valfritt

Här är JSON-exempel som innehåller uttalsutvärderingsparametrarna:

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

Följande exempelkod visar hur du skapar uttalsutvärderingsparametrarna i Pronunciation-Assessment rubriken:

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

Vi rekommenderar starkt uppladdning av direktuppspelning (segmenterad överföring) när du publicerar ljuddata, vilket avsevärt kan minska svarstiden. Information om hur du aktiverar strömning finns i exempelkoden på olika programmeringsspråk.

Kommentar

Mer information finns i uttalsbedömning.

Exempelbegäran

Följande exempel innehåller värdnamnet och nödvändiga rubriker. Det är viktigt att observera att tjänsten också förväntar sig ljuddata, som inte ingår i det här exemplet. Som tidigare nämnts rekommenderas segmentering men krävs inte.

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

Om du vill aktivera uttalsutvärdering kan du lägga till följande rubrik. Information om hur du skapar den här rubriken finns i Utvärderingsparametrar för uttal.

Pronunciation-Assessment: eyJSZWZlcm...

HTTP-statuskoder

HTTP-statuskoden för varje svar anger lyckade eller vanliga fel.

HTTP-statuskod	beskrivning	Möjliga orsaker
100	Fortsätt	Den första begäran godkänns. Fortsätt med att skicka resten av data. (Den här koden används med segmenterad överföring.)
200	OK	Begäran lyckades. Svarstexten är ett JSON-objekt.
400	Felaktig begäran	Språkkoden angavs inte, språket stöds inte eller så är ljudfilen ogiltig (till exempel).
401	Behörighet saknas	En resursnyckel eller en auktoriseringstoken är ogiltig i den angivna regionen, eller så är en slutpunkt ogiltig.
403	Ej tillåtet	En resursnyckel eller auktoriseringstoken saknas.

Exempelsvar

Här är ett typiskt svar för simple igenkänning:

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

Här är ett typiskt svar för detailed igenkänning:

{
  "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"
    }
  ]
}

Här är ett typiskt svar för igenkänning med uttalsbedömning:

{
  "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
            }
        ]
      }
  ]
}

Svarsegenskaper

Resultaten tillhandahålls som JSON. Formatet simple innehåller följande fält på den översta nivån:

Property	beskrivning
`RecognitionStatus`	Status, till exempel `Success` för lyckad igenkänning. Visa nästa tabell.
`DisplayText`	Den identifierade texten efter versaler, skiljetecken, inverterad textnormalisering och svordomsmaskering. Presentera endast för framgång. Inverterad textnormalisering är konvertering av talad text till kortare former, till exempel 200 för "två hundra" eller "Dr. Smith" för "doctor smith".
`Offset`	Tiden (i 100 nanosekunder) då det igenkända talet börjar i ljudströmmen.
`Duration`	Varaktigheten (i 100 nanosekunder) för det igenkända talet i ljudströmmen.

Fältet RecognitionStatus kan innehålla följande värden:

Status	beskrivning
`Success`	Igenkänningen lyckades och fältet `DisplayText` finns.
`NoMatch`	Tal upptäcktes i ljudströmmen, men inga ord från målspråket matchades. Den här statusen innebär vanligtvis att igenkänningsspråket skiljer sig från det språk som användaren talar.
`InitialSilenceTimeout`	Starten av ljudströmmen innehöll endast tystnad, och tjänsten tidsgränserades i väntan på tal.
`BabbleTimeout`	Starten av ljudströmmen innehöll endast brus, och tjänstens timeout i väntan på tal.
`Error`	Igenkänningstjänsten påträffade ett internt fel och kunde inte fortsätta. Försök igen om det är möjligt.

Kommentar

Om ljudet endast består av svordomar och profanity frågeparametern är inställd på removereturnerar tjänsten inte något talresultat.

Formatet detailed innehåller fler former av identifierade resultat. När du använder detailed formatet DisplayText tillhandahålls som Display för varje resultat i NBest listan.

Objektet i NBest listan kan innehålla:

Property	beskrivning
`Confidence`	Konfidenspoängen för posten, från 0,0 (ej konfidens) till 1,0 (fullständigt förtroende).
`Lexical`	Den lexikala formen av den identifierade texten: de faktiska orden som känns igen.
`ITN`	Den inverterade textnormaliserade (ITN) eller kanoniska formen av den igenkända texten, med telefonnummer, siffror, förkortningar ("doctor smith" till "dr smith" och andra transformeringar som tillämpas.
`MaskedITN`	ITN-formuläret med svordomsmaskering tillämpas om det begärs.
`Display`	Visningsformen för den tolkade texten, med skiljetecken och versaler tillagda. Den här parametern är samma som den som `DisplayText` anger när formatet är inställt på `simple`.
`AccuracyScore`	Uttalsprecision av talet. Noggrannhet anger hur nära phonemes matchar uttal från en infödd talare. Noggrannhetspoängen på ord- och fulltextnivåerna aggregeras från noggrannhetspoängen på fonetiknivå.
`FluencyScore`	Flytande av det angivna talet. Fluency anger hur nära talet matchar en infödd talares användning av tysta brytningar mellan ord.
`CompletenessScore`	Talets fullständighet bestäms genom beräkning av förhållandet mellan uttalade ord och referenstextinmatning.
`PronScore`	Övergripande poäng som anger uttalskvaliteten för det angivna talet. Den här poängen aggregeras från `AccuracyScore`, `FluencyScore`och `CompletenessScore` med vikt.
`ErrorType`	Värde som anger om ett ord utelämnas, infogas eller är dåligt uttalat jämfört med `ReferenceText`. Möjliga värden är `None` (vilket betyder inget fel på det här ordet), `Omission`, `Insertion`, och `Mispronunciation`.

Segmenterad överföring

Segmenterad överföring (Transfer-Encoding: chunked) kan minska svarstiden för igenkänning. Det gör att Speech-tjänsten kan börja bearbeta ljudfilen medan den överförs. REST-API:et för kort ljud ger inte partiella eller interimistiska resultat.

Följande kodexempel visar hur du skickar ljud i segment. Endast det första segmentet ska innehålla ljudfilens huvud. request är ett HttpWebRequest objekt som är anslutet till rätt REST-slutpunkt. audioFile är sökvägen till en ljudfil på disken.

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();
    }
}

Autentisering

Varje begäran kräver ett auktoriseringshuvud. Den här tabellen visar vilka rubriker som stöds för varje funktion:

Auktoriseringshuvud som stöds	Tal till text	Text till tal
`Ocp-Apim-Subscription-Key`	Ja	Ja
`Authorization: Bearer`	Ja	Ja

När du använder Ocp-Apim-Subscription-Key huvudet måste endast resursnyckeln anges. Till exempel:

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

När du använder Authorization: Bearer huvudet måste du göra en begäran till issueToken slutpunkten. I den här begäran byter du ut resursnyckeln mot en åtkomsttoken som är giltig i 10 minuter.

Ett annat alternativ är att använda Microsoft Entra-autentisering som också använder Authorization: Bearer huvudet, men med en token utfärdad via Microsoft Entra-ID. Se Använda Microsoft Entra-autentisering.

Så här skaffar du en åtkomsttoken

För att få en åtkomsttoken måste du göra en begäran till issueToken slutpunkten med hjälp Ocp-Apim-Subscription-Key av och din resursnyckel.

Slutpunkten issueToken har följande format:

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

Ersätt <REGION_IDENTIFIER> med identifieraren som matchar prenumerationens region .

Använd följande exempel för att skapa din begäran om åtkomsttoken.

HTTP-exempel

Det här exemplet är en enkel HTTP-begäran för att hämta en token. Ersätt YOUR_SUBSCRIPTION_KEY med resursnyckeln för Speech-tjänsten. Om din prenumeration inte finns i regionen USA, västra ersätter du Host huvudet med regionens värdnamn.

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

Brödtexten i svaret innehåller åtkomsttoken i JSON Web Token-format (JWT).

PowerShell-exempel

Det här exemplet är ett enkelt PowerShell-skript för att hämta en åtkomsttoken. Ersätt YOUR_SUBSCRIPTION_KEY med resursnyckeln för Speech-tjänsten. Se till att använda rätt slutpunkt för den region som matchar din prenumeration. Det här exemplet är för närvarande inställt på USA, västra.

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

cURL är ett kommandoradsverktyg som är tillgängligt i Linux (och i Windows-undersystem för Linux). Det här cURL-kommandot visar hur du hämtar en åtkomsttoken. Ersätt YOUR_SUBSCRIPTION_KEY med resursnyckeln för Speech-tjänsten. Se till att använda rätt slutpunkt för den region som matchar din prenumeration. Det här exemplet är för närvarande inställt på USA, västra.

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

Den här C#-klassen visar hur du hämtar en åtkomsttoken. Skicka resursnyckeln för Speech-tjänsten när du instansierar klassen. Om din prenumeration inte finns i regionen USA, västra ändrar du värdet FetchTokenUri för så att det matchar regionen för din prenumeration.

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

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

Så här använder du en åtkomsttoken

Åtkomsttoken ska skickas till tjänsten som Authorization: Bearer <TOKEN> rubrik. Varje åtkomsttoken är giltig i 10 minuter. Du kan hämta en ny token när som helst, men för att minimera nätverkstrafiken och svarstiden rekommenderar vi att du använder samma token i nio minuter.

Här är en HTTP-exempelbegäran till REST API för tal till text för kort ljud:

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

Använd Microsoft Entra-autentisering

Om du vill använda Microsoft Entra-autentisering med REST API för tal till text för kort ljud måste du skapa en åtkomsttoken. Stegen för att hämta åtkomsttoken som består av resurs-ID och Microsoft Entra-åtkomsttoken är desamma som när du använder Speech SDK. Följ stegen här Använda Microsoft Entra-autentisering

Skapa en Speech-resurs
Konfigurera Speech-resursen för Microsoft Entra-autentisering
Hämta en Microsoft Entra-åtkomsttoken
Hämta resurs-ID för Tal

När resurs-ID:t och Microsoft Entra-åtkomsttoken har hämtats kan den faktiska åtkomsttoken konstrueras enligt det här formatet:

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Du måste inkludera prefixet "aad#" och "#" (hash)-avgränsaren mellan resurs-ID och åtkomsttoken.

Här är en HTTP-exempelbegäran till REST API för tal till text för kort ljud:

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

Mer information om Microsoft Entra-åtkomsttoken, inklusive tokenlivslängd, finns i Åtkomsttoken i Microsofts identitetsplattform.

Dela via

Rest-API för tal till text för kort ljud

Regioner och slutpunkter

Ljudformat

Begärandehuvuden

Frågeparametrar

Utvärderingsparametrar för uttal

Exempelbegäran

HTTP-statuskoder

Exempelsvar

Svarsegenskaper

Segmenterad överföring

Autentisering

Så här skaffar du en åtkomsttoken

HTTP-exempel

PowerShell-exempel

cURL-exempel

C#-exempel

Python-exempel

Så här använder du en åtkomsttoken

Använd Microsoft Entra-autentisering

Nästa steg

Feedback

Ytterligare resurser