Usare l'API REST da voce a testo per brevi file audio

Usare l'API REST Riconoscimento vocale per l'audio breve solo nei casi in cui non è possibile usare l'SDK Voce o l'API di trascrizione rapida.

Prima di usare l'API REST da Voce a Testo per l'audio breve, tenere presente le seguenti limitazioni:

• Le richieste che usano l'API REST per l'audio breve e la trasmissione diretta dell'audio non possono contenere più di 60 secondi di audio. Per la valutazione della pronuncia, la durata audio non deve superare i 30 secondi. I formati audio di input sono più limitati rispetto a Speech SDK.
• L'API REST per l'audio breve restituisce solo i risultati finali. Non fornisce risultati parziali.
• La traduzione vocale non è supportata tramite l'API REST per l'audio breve. È necessario usare Speech SDK.
• La trascrizione batch e il riconoscimento vocale personalizzato non sono supportati tramite l'API REST per l'audio breve. È consigliabile usare sempre la Speech to text REST API per la trascrizione batch e il discorso personalizzato.

Prima di usare l'API REST Riconoscimento vocale per audio brevi, è necessario completare uno scambio di token come parte dell'autenticazione per accedere al servizio. Per altre informazioni, vedere Autenticazione.

Aree ed endpoint

L'endpoint per l'API REST per audio breve ha questo formato:

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

Sostituisci YourResourceName con il nome della tua risorsa Speech.

Formati audio

L'audio viene inviato nel corpo della richiesta HTTP POST . Deve essere in uno dei formati in questa tabella:

Intestazioni della richiesta

Questa tabella elenca le intestazioni obbligatorie e facoltative per le richieste di trascrizione vocale.

Parametri di query

Questi parametri potrebbero essere inclusi nella stringa di query della richiesta REST.

Parametri di valutazione della pronuncia

Questa tabella elenca i parametri obbligatori e facoltativi per la valutazione della pronuncia:

Ecco un esempio json che contiene i parametri di valutazione della pronuncia:

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

Il codice di esempio seguente illustra come compilare i parametri di valutazione della pronuncia nell'intestazione Pronunciation-Assessment :

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

Raccomandiamo vivamente di effettuare l'upload in streaming (trasferimento in blocchi) durante il caricamento dei dati audio, riducendo in modo significativo la latenza. Per informazioni su come abilitare lo streaming, vedere il codice sample in vari linguaggi di programmazione.

Richiesta di esempio

L'esempio seguente include il nome host e le intestazioni obbligatorie. È importante notare che il servizio prevede anche dati audio, che non sono inclusi in questo esempio. Come accennato in precedenza, la suddivisione in blocchi è consigliata ma non obbligatoria.

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

Per abilitare la valutazione della pronuncia, è possibile aggiungere l'intestazione seguente. Per informazioni su come creare questa intestazione, vedere Parametri di valutazione della pronuncia.

Pronunciation-Assessment: eyJSZWZlcm...

Codici di stato HTTP

Il codice di stato HTTP per ogni risposta indica il successo o errori comuni.

Risposte di esempio

Ecco una risposta tipica per il riconoscimento simple:

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

Ecco una risposta tipica per il riconoscimento 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"
    }
  ]
}

Ecco una risposta tipica per il riconoscimento con la valutazione della pronuncia:

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

Proprietà della risposta

I risultati vengono forniti come JSON. Il simple formato include i campi di primo livello seguenti:

Il RecognitionStatus campo può contenere questi valori:

Il detailed formato include più forme di risultati riconosciuti. Quando si usa il detailed formato, DisplayText viene fornito come Display per ogni risultato nell'elenco NBest .

L'oggetto nell'elenco NBest può includere:

Trasferimento in blocchi

Il trasferimento in blocchi (Transfer-Encoding: chunked) può contribuire a ridurre la latenza di riconoscimento. Consente al servizio Voce di iniziare a elaborare il file audio durante la trasmissione. L'API REST per l'audio breve non fornisce risultati parziali o provvisori.

L'esempio di codice seguente illustra come inviare audio in blocchi. Solo il primo blocco deve contenere l'intestazione del file audio. request è un HttpWebRequest oggetto connesso all'endpoint REST appropriato. audioFile è il percorso di un file audio su disco.

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

Autenticazione

Ogni richiesta richiede un'intestazione di autorizzazione. Questa tabella illustra le intestazioni supportate per ogni funzionalità:

Quando si usa l'intestazione Ocp-Apim-Subscription-Key , è necessario specificare solo la chiave di risorsa. Per esempio:

'Ocp-Apim-Subscription-Key': 'YourSpeechResourceKey'

Se si usa il flusso con token bearer STS con Authorization: Bearer, inviare prima una richiesta all'endpoint issueToken. In questa richiesta si scambia la chiave della risorsa per un token di accesso valido per 10 minuti.

Un'altra opzione consiste nell'usare l'autenticazione Microsoft Entra che usa anche l'intestazione Authorization: Bearer, ma con un token rilasciato tramite Microsoft Entra ID. Vedere Usa l'autenticazione di Microsoft Entra.

Come ottenere un token di accesso STS

Per ottenere un token di accesso STS, invia una richiesta all'endpoint issueToken utilizzando Ocp-Apim-Subscription-Key e la chiave della risorsa.

L'endpoint issueToken ha questo formato:

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

Sostituisci YourResourceName con il nome della tua risorsa Speech.

Usare gli esempi seguenti per creare la richiesta di token di accesso.

Esempio HTTP

Questo esempio è una semplice richiesta HTTP per ottenere un token. Sostituire YourSpeechResourceKey con la chiave di risorsa per il servizio Speech. Sostituisci YourResourceName con il nome della tua risorsa Speech.

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

Il corpo della risposta contiene il token di accesso in formato JWT (JSON Web Token).

Esempio di PowerShell

Questo esempio è un semplice script di PowerShell per ottenere un token di accesso. Sostituire YourSpeechResourceKey con la chiave di risorsa per il servizio Speech. Sostituisci YourResourceName con il nome della tua risorsa Speech.

$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

Esempio cURL

cURL è uno strumento da riga di comando disponibile in Linux (e nel sottosistema Windows per Linux). Questo comando cURL illustra come ottenere un token di accesso. Sostituire YourSpeechResourceKey con la chiave di risorsa per il servizio Speech. Sostituisci YourResourceName con il nome della tua risorsa Speech.

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"

Esempio C#

Questa classe C# illustra come ottenere un token di accesso. Passare la chiave di risorsa per il servizio Voce quando si crea un'istanza della classe. Sostituisci YourResourceName con il nome della tua risorsa Speech.

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

esempio di 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)

Come usare un token di accesso

Il token di accesso deve essere inviato al servizio nell'intestazione Authorization: Bearer <TOKEN>. Ogni token di accesso è valido per 10 minuti. È possibile ottenere un nuovo token in qualsiasi momento, ma per ridurre al minimo il traffico di rete e la latenza, è consigliabile usare lo stesso token per nove minuti.

Ecco una richiesta HTTP di esempio all'API REST Speech to text per audio brevi:

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

Usare l'autenticazione Microsoft Entra

Per usare l'autenticazione di Microsoft Entra con l'API REST da voce a testo per audio breve, è necessario creare un token di accesso. I passaggi per ottenere il token di accesso costituito dall'ID risorsa e dal token di accesso di Microsoft Entra sono gli stessi di quando si utilizza il Speech SDK. Seguire questa procedura Usare l'autenticazione Microsoft Entra

Dopo aver ottenuto l'ID risorsa e il token di accesso Microsoft Entra, il token di accesso effettivo può essere costruito seguendo questo formato:

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

È necessario includere il prefisso "aad#" e il separatore "#" (hash) tra l'ID risorsa e il token di accesso.

Ecco una richiesta HTTP di esempio all'API REST Speech to text per audio brevi:

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

Per altre informazioni sui token di accesso Microsoft Entra, inclusa la durata dei token, visitare Access tokens in the Microsoft Identity Platform.

Contenuto correlato

• API di trascrizione rapida
• Personalizzare i modelli di riconoscimento vocale
• Familiarizzarsi con la trascrizione batch