Rozhraní REST API pro převod řeči na text pro krátký zvuk

Případy použití rozhraní REST API pro převod řeči na text jsou omezené. Používejte ho jenom v případech, kdy nemůžete použít sadu Speech SDK.

Než použijete rozhraní REST API pro převod řeči na text pro krátký zvuk, zvažte následující omezení:

• Požadavky, které používají rozhraní REST API pro krátký zvuk a přenášejí zvuk přímo, nesmí obsahovat více než 60 sekund zvuku. Formáty vstupního zvuku jsou ve srovnání se sadou Speech SDK omezenější.
• Rozhraní REST API pro krátký zvuk vrátí pouze konečné výsledky. Neposkytuje částečné výsledky.
• Překlad řeči se nepodporuje prostřednictvím rozhraní REST API pro krátký zvuk. Potřebujete použít sadu Speech SDK.
• Dávkové přepisy a vlastní řeč nejsou podporovány prostřednictvím rozhraní REST API pro krátký zvuk. K dávkovému přepisu a vlastní řeči byste měli vždy používat rozhraní REST API pro převod řeči na text.

Než použijete rozhraní Speech k textovému rozhraní REST API pro krátký zvuk, uvědomte si, že pro přístup ke službě potřebujete dokončit výměnu tokenů. Další informace najdete v tématu Ověřování.

Oblasti a koncové body

Koncový bod rozhraní REST API pro krátký zvuk má tento formát:

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

Nahraďte <REGION_IDENTIFIER> identifikátorem, který odpovídá oblasti vašeho prostředku služby Speech.

Formáty zvuku

Zvuk se odešle v textu požadavku HTTP POST . Musí být v jednom z formátů v této tabulce:

Záhlaví žádosti

Tato tabulka obsahuje seznam povinných a volitelných hlaviček pro požadavky na převod řeči na text:

Parametry dotazů

Tyto parametry mohou být zahrnuty do řetězce dotazu požadavku REST.

Parametry posouzení výslovnosti

Tato tabulka obsahuje seznam povinných a volitelných parametrů pro vyhodnocení výslovnosti:

Tady je příklad KÓDU JSON, který obsahuje parametry vyhodnocení výslovnosti:

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

Následující ukázkový kód ukazuje, jak do hlavičky Pronunciation-Assessment sestavit parametry vyhodnocení výslovnosti:

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

Při odesílání zvukových dat důrazně doporučujeme nahrávat streamované (blokované přenosy), což může výrazně snížit latenci. Informace o povolení streamování najdete v ukázkovém kódu v různých programovacích jazycích.

Ukázkový požadavek

Následující ukázka obsahuje název hostitele a požadované hlavičky. Je důležité si uvědomit, že služba také očekává zvuková data, která nejsou součástí této ukázky. Jak už bylo zmíněno dříve, doporučuje se, ale nevyžaduje se vytváření bloků dat.

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

Pokud chcete povolit hodnocení výslovnosti, můžete přidat následující hlavičku. Informace o tom, jak vytvořit tuto hlavičku, najdete v tématu Parametry posouzení výslovnosti.

Pronunciation-Assessment: eyJSZWZlcm...

Stavové kódy HTTP

Stavový kód HTTP pro každou odpověď označuje úspěch nebo běžné chyby.

Ukázkové odpovědi

Tady je typická odpověď pro simple rozpoznávání:

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

Tady je typická odpověď pro detailed rozpoznávání:

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

Tady je typická odpověď pro rozpoznávání pomocí vyhodnocení výslovnosti:

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

Vlastnosti odpovědi

Výsledky jsou k dispozici ve formátu JSON. Formát simple obsahuje následující pole nejvyšší úrovně:

Pole RecognitionStatus může obsahovat tyto hodnoty:

Formát detailed obsahuje více forem rozpoznaných výsledků. Pokud používáte detailed formát, DisplayText zobrazí se pro Display každý výsledek v NBest seznamu.

Objekt v NBest seznamu může obsahovat:

Přenos s blokem dat

Blokovaný přenos (Transfer-Encoding: chunked) může pomoct snížit latenci rozpoznávání. Služba Speech umožňuje zahájit zpracování zvukového souboru během přenosu. Rozhraní REST API pro krátký zvuk neposkytuje částečné ani dočasné výsledky.

Následující ukázka kódu ukazuje, jak odeslat zvuk v blocích dat. Záhlaví zvukového souboru by mělo obsahovat pouze první blok dat. requestHttpWebRequest je objekt, který je připojený k příslušnému koncovému bodu REST. audioFile je cesta ke zvukovému souboru na disku.

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

Ověřování

Každý požadavek vyžaduje autorizační hlavičku. Tato tabulka znázorňuje, která záhlaví jsou pro každou funkci podporovaná:

Pokud používáte hlavičku Ocp-Apim-Subscription-Key , musíte zadat jenom klíč prostředku. Příklad:

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

Když používáte hlavičku Authorization: Bearer , musíte do koncového issueToken bodu vytvořit požadavek. V této žádosti si vyměníte svůj klíč prostředku za přístupový token, který je platný 10 minut.

Další možností je použít ověřování Microsoft Entra, které také používá hlavičku Authorization: Bearer , ale s tokenem vydaným prostřednictvím ID Microsoft Entra. Viz Použití ověřování Microsoft Entra.

Jak získat přístupový token

Pokud chcete získat přístupový token, musíte do koncového issueToken bodu vytvořit požadavek pomocí Ocp-Apim-Subscription-Key svého klíče prostředku.

Koncový issueToken bod má tento formát:

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

Nahraďte <REGION_IDENTIFIER> identifikátorem, který odpovídá oblasti vašeho předplatného.

K vytvoření žádosti o přístupový token použijte následující ukázky.

Ukázka PROTOKOLU HTTP

Tento příklad je jednoduchý požadavek HTTP pro získání tokenu. Nahraďte YOUR_SUBSCRIPTION_KEY klíčem prostředku pro službu Speech. Pokud vaše předplatné není v oblasti USA – západ, nahraďte Host záhlaví názvem hostitele vaší oblasti.

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

Text odpovědi obsahuje přístupový token ve formátu JSON Web Token (JWT).

Ukázka PowerShellu

Tento příklad je jednoduchý skript PowerShellu pro získání přístupového tokenu. Nahraďte YOUR_SUBSCRIPTION_KEY klíčem prostředku pro službu Speech. Ujistěte se, že používáte správný koncový bod pro oblast, která odpovídá vašemu předplatnému. Tento příklad je aktuálně nastavený na USA – západ.

$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

Ukázka cURL

cURL je nástroj příkazového řádku dostupný v Linuxu (a v Subsystém Windows pro Linux). Tento příkaz cURL ukazuje, jak získat přístupový token. Nahraďte YOUR_SUBSCRIPTION_KEY klíčem prostředku pro službu Speech. Ujistěte se, že používáte správný koncový bod pro oblast, která odpovídá vašemu předplatnému. Tento příklad je aktuálně nastavený na USA – západ.

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"

Ukázka v jazyce C#

Tato třída jazyka C# ukazuje, jak získat přístupový token. Klíč prostředku pro službu Speech předejte při vytváření instance třídy. Pokud vaše předplatné není v oblasti USA – západ, změňte hodnotu FetchTokenUri tak, aby odpovídala oblasti vašeho předplatného.

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

Ukázka Pythonu

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

Jak používat přístupový token

Přístupový token by měl být odeslán do služby jako hlavička Authorization: Bearer <TOKEN> . Každý přístupový token je platný po dobu 10 minut. Nový token můžete kdykoli získat, ale pokud chcete minimalizovat síťový provoz a latenci, doporučujeme použít stejný token po dobu devíti minut.

Tady je ukázkový požadavek HTTP na rozhraní REST API pro převod řeči na text pro krátký zvuk:

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

Používání ověřování Microsoft Entra

Pokud chcete pro krátký zvuk použít ověřování Microsoft Entra s rozhraním REST API pro převod řeči na text, musíte vytvořit přístupový token. Postup získání přístupového tokenu, který se skládá z ID prostředku a přístupového tokenu Microsoft Entra, jsou stejné jako při použití sady Speech SDK. Postupujte podle zde uvedených kroků, použijte ověřování Microsoft Entra.

Po získání ID prostředku a přístupového tokenu Microsoft Entra lze skutečný přístupový token vytvořit pomocí tohoto formátu:

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Musíte zahrnout předponu "aad#" a oddělovač hodnot hash (#) mezi ID prostředku a přístupový token.

Tady je ukázkový požadavek HTTP na rozhraní REST API pro převod řeči na text pro krátký zvuk:

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

Další informace o přístupovýchtokench

Další kroky

• Přizpůsobení hlasových modelů
• Seznámení s dávkovým přepisem