Condividi tramite

API REST di riconoscimento vocale per audio brevi

  • Articolo

I casi d'uso per l'API REST Riconoscimento vocale per audio breve sono limitati. Usarlo solo nei casi in cui non è possibile usare Speech SDK.

Prima di usare l'API REST Riconoscimento vocale per l'audio breve, prendere in considerazione le limitazioni seguenti:

Prima di usare l'API REST Riconoscimento vocale per l'audio breve, è 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://<REGION_IDENTIFIER>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1

Sostituire <REGION_IDENTIFIER> con l'identificatore corrispondente all'area della risorsa Voce.

Nota

Per Azure per enti pubblici e Microsoft Azure gestito da 21 EndpointVianet, vedere questo articolo sui cloud sovrani.

Formati audio

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

Formato Codec Velocità in bit Frequenza di campionamento
WAV PCM 256 Kbps 16 kHz, mono
OGG OPUS 256 Kbps 16 kHz, mono

Nota

I formati precedenti sono supportati tramite l'API REST per brevi audio e WebSocket nel servizio Voce. Speech SDK supporta il formato WAV con codec PCM e altri formati.

Intestazioni delle richieste

Questa tabella elenca le intestazioni obbligatorie e facoltative per le richieste di riconoscimento vocale:

Intestazione Descrizione Obbligatorio o facoltativo
Ocp-Apim-Subscription-Key Chiave di risorsa per il servizio Voce. È necessaria questa intestazione o Authorization.
Authorization Un token di autorizzazione preceduto dalla parola Bearer. Per altre informazioni, vedere Autenticazione. È necessaria questa intestazione o Ocp-Apim-Subscription-Key.
Pronunciation-Assessment Specifica i parametri per visualizzare i punteggi di pronuncia nei risultati del riconoscimento. Questi punteggi valutano la qualità della pronuncia dell'input vocale, con indicatori come accuratezza, fluenza e completezza.

Questo parametro è un json con codifica Base64 che contiene più parametri dettagliati. Per informazioni su come creare questa intestazione, vedere Parametri di valutazione della pronuncia.		 Facoltativo
Content-type Descrive il formato e il codec dei dati audio forniti. I valori accettati sono audio/wav; codecs=audio/pcm; samplerate=16000 e audio/ogg; codecs=opus. Richiesto
Transfer-Encoding Specifica che vengono inviati i dati audio in blocchi, anziché un singolo file. Usare questa intestazione solo se si usano dati audio in blocchi. Facoltativo
Expect Se si usa il trasferimento in blocchi, inviare Expect: 100-continue. Il servizio Voce riconosce la richiesta iniziale e attende più dati. Obbligatorio se si inviano dati audio in blocchi.
Accept Se specificato, deve essere application/json. Il servizio Voce fornisce risultati in JSON. Alcuni framework di richiesta forniscono un valore predefinito incompatibile. È consigliabile includere Acceptsempre . Facoltativo, ma consigliato.

Parametri di query

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

Nota

È necessario aggiungere il parametro language all'URL per evitare di ricevere un errore HTTP 4xx. Ad esempio, la lingua impostata su Inglese stati Uniti tramite l'endpoint Stati Uniti occidentali è: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Parametro Descrizione Obbligatorio o facoltativo
language Identifica la lingua parlata riconosciuta. Vedere Lingue supportate. Richiesto
format Specifica il formato del risultato. I valori accettati sono simple e detailed. I risultati semplici includono RecognitionStatus, DisplayText, Offset e Duration. Le risposte dettagliate includono quattro diverse rappresentazioni del testo visualizzato. L'impostazione predefinita è simple. Facoltativo
profanity Specifica come gestire il linguaggio volgare nei risultati del riconoscimento. I valori accettati sono:

masked, che sostituisce il contenuto volgare con asterischi.
removed, che rimuove tutte le espressioni volgari dal risultato.
raw, che include contenuto volgare nel risultato.

L'impostazione predefinita è masked.		 Facoltativo
cid Quando si usa Speech Studio per creare modelli personalizzati, è possibile sfruttare il valore dell'ID endpoint dalla pagina Distribuzione. Usare il valore endpoint ID come argomento per il parametro della cid stringa di query. Facoltativo

Parametri di valutazione della pronuncia

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

Parametro Descrizione Obbligatorio o facoltativo
ReferenceText Testo rispetto al quale viene valutata la pronuncia. Richiesto
GradingSystem Sistema di punti per la calibrazione del punteggio. Il sistema FivePoint assegna un punteggio a virgola mobile da 0 a 5 e HundredMark assegna un punteggio a virgola mobile pari a 0-100. Impostazione predefinita: FivePoint. Facoltativo
Granularity Granularità della valutazione. I valori accettati sono:

Phoneme, che mostra il punteggio sui livelli full-text, word e phoneme.
Word, che mostra il punteggio nei livelli full-text e word.
FullText, che mostra il punteggio solo a livello full-text.

L'impostazione predefinita è Phoneme.		 Facoltativo
Dimension Definisce i criteri di output. I valori accettati sono:

Basic, che mostra solo il punteggio di accuratezza.
Comprehensive, che mostra i punteggi su più dimensioni (ad esempio, punteggio di fluenza e punteggio di completezza sul livello full-text e tipo di errore a livello di parola).

Per visualizzare le definizioni di diverse dimensioni del punteggio e tipi di errore delle parole, vedere Proprietà della risposta. L'impostazione predefinita è Basic.		 Facoltativo
EnableMiscue Abilita il calcolo miscue. Con questo parametro abilitato, le parole pronunciate vengono confrontate con il testo di riferimento. Sono contrassegnati con omissione o inserimento in base al confronto. I valori accettati sono False e True. L'impostazione predefinita è False. Facoltativo
ScenarioId GUID che indica un sistema di punti personalizzato. Facoltativo

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

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

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\":\"FullText\",\"Dimension\":\"Comprehensive\"}}";
var pronAssessmentParamsBytes = Encoding.UTF8.GetBytes(pronAssessmentParamsJson);
var pronAssessmentHeader = Convert.ToBase64String(pronAssessmentParamsBytes);

È consigliabile caricare lo streaming (trasferimento in blocchi) durante la pubblicazione dei dati audio, riducendo in modo significativo la latenza. Per informazioni su come abilitare lo streaming, vedere il codice di esempio in vari linguaggi di programmazione.

Nota

Per altre informazioni, vedere Valutazione della pronuncia.

Esempio di richiesta

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: westus.stt.speech.microsoft.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 di ogni risposta indica esito positivo o errori comuni.

Codice di stato HTTP Descrizione Possibili cause
100 Continua La richiesta iniziale viene accettata. Procedere con l'invio del resto dei dati. Questo codice viene usato con il trasferimento in blocchi.
200 OK La richiesta è stata completata. Il corpo della risposta è un oggetto JSON.
400 Richiesta non valida Il codice della lingua non è stato fornito, la lingua non è supportata o il file audio non è valido (ad esempio).
401 Non autorizzata Una chiave di risorsa o un token di autorizzazione non è valida nell'area specificata oppure un endpoint non è valido.
403 Non consentito Manca una chiave di risorsa o un token di autorizzazione.

Risposte di esempio

Ecco una risposta tipica per simple il riconoscimento:

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

Ecco una risposta tipica per detailed il riconoscimento:

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

Proprietà della risposta

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

Proprietà Descrizione
RecognitionStatus Lo stato, ad esempio Success per il riconoscimento con esito positivo. Vedere la tabella seguente.
DisplayText Testo riconosciuto dopo la maiuscola, la punteggiatura, la normalizzazione del testo inversa e il mascheramento delle espressioni volgari. Presente solo con esito positivo. La normalizzazione del testo inversa è la conversione di testo parlato in forme più brevi, ad esempio 200 per "200" o "Dr. Smith" per "doctor smith".
Offset Il tempo (in unità di 100 nanosecondi) in corrispondenza del quale inizia l'input vocale riconosciuto nel flusso audio.
Duration La durata (in unità di 100 nanosecondi) dell'input vocale riconosciuto nel flusso audio.

Il RecognitionStatus campo può contenere questi valori:

Stato Descrizione
Success Il riconoscimento è riuscito e il DisplayText campo è presente.
NoMatch La parte parlata è stata rilevata nel flusso audio, ma non sono state trovate corrispondenze per alcuna parola nella lingua di destinazione. Questo stato significa in genere che la lingua di riconoscimento è diversa dalla lingua che l'utente sta parlando.
InitialSilenceTimeout L'inizio del flusso audio conteneva solo il silenzio e il servizio si è timeout durante l'attesa del parlato.
BabbleTimeout L'inizio del flusso audio conteneva solo rumore e il servizio si è timeout durante l'attesa della voce.
Error Il servizio di riconoscimento ha rilevato un errore interno e non è stato possibile continuare. Provare di nuovo, se possibile.

Nota

Se l'audio è costituito solo da contenuto volgare e il parametro di query profanity è impostato su remove, il servizio non restituisce un risultato di riconoscimento vocale.

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:

Proprietà Descrizione
Confidence Punteggio di attendibilità della voce, da 0,0 (senza attendibilità) a 1,0 (attendibilità completa).
Lexical Il formato lessicale del testo riconosciuto: le parole effettive riconosciute.
ITN La forma inversa normalizzata (ITN) o canonica del testo riconosciuto, con numeri di telefono, numeri, abbreviazioni ("doctor smith" a "dr smith") e altre trasformazioni applicate.
MaskedITN La forma ITN con la maschera per le volgarità applicata, se richiesta.
Display Il modulo di visualizzazione del testo riconosciuto, con l'aggiunta di segni di punteggiatura e maiuscole. Questo parametro è uguale a quello DisplayText fornito quando il formato è impostato su simple.
AccuracyScore Accuratezza della pronuncia del parlato. L'accuratezza indica quanto i fonemi corrispondano alla pronuncia di un parlante nativo. Il punteggio di accuratezza a livello di parola e full-text viene aggregato dal punteggio di accuratezza a livello di fonema.
FluencyScore Fluenza del discorso fornito. La scorrevolezza indica quanto il parlato corrisponda all'uso di un parlante nativo di interruzioni silenziose tra le parole.
CompletenessScore Completezza del parlato, determinato calcolando il rapporto tra parole pronunciate e input di testo di riferimento.
PronScore Punteggio complessivo che indica la qualità della pronuncia del parlato fornito. Questo punteggio viene aggregato da AccuracyScore, FluencyScoree CompletenessScore con peso.
ErrorType Valore che indica se una parola viene omessa, inserita o pronunciata in modo non valido, rispetto a ReferenceText. I valori possibili sono None (ovvero nessun errore in questa parola), Omission, Insertione Mispronunciation.

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à:

Intestazione di autorizzazione supportata Riconoscimento vocale Sintesi vocale
Ocp-Apim-Subscription-Key Sì Sì
Authorization: Bearer Sì Sì

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

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

Quando si usa l'intestazione Authorization: Bearer , è necessario effettuare 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 di Microsoft Entra che usa anche l'intestazione Authorization: Bearer , ma con un token rilasciato tramite Microsoft Entra ID. Vedere Usare l'autenticazione di Microsoft Entra.

Come ottenere un token di accesso

Per ottenere un token di accesso, è necessario effettuare una richiesta all'endpoint issueToken usando Ocp-Apim-Subscription-Key e la chiave della risorsa.

L'endpoint issueToken ha questo formato:

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

Sostituire <REGION_IDENTIFIER> con l'identificatore corrispondente all'area della sottoscrizione.

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

Esempio di HTTP

Questo esempio è una semplice richiesta HTTP per ottenere un token. Sostituire YOUR_SUBSCRIPTION_KEY con la chiave di risorsa per il servizio Voce. Se la sottoscrizione non si trova nell'area Stati Uniti occidentali, sostituire l'intestazione Host con il nome host della propria area.

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

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

Esempio PowerShell

Questo esempio è un semplice script di PowerShell per ottenere un token di accesso. Sostituire YOUR_SUBSCRIPTION_KEY con la chiave di risorsa per il servizio Voce. Assicurarsi di usare l'endpoint corretto per l'area che corrisponde alla sottoscrizione. Questo esempio è attualmente impostato sugli Stati Uniti occidentali.

$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

esempio di cURL

cURL è uno strumento da riga di comando disponibile in Linux (e nel sottosistema Windows per Linux). Il comando cURL illustra come ottenere un token di accesso. Sostituire YOUR_SUBSCRIPTION_KEY con la chiave di risorsa per il servizio Voce. Assicurarsi di usare l'endpoint corretto per l'area che corrisponde alla sottoscrizione. Questo esempio è attualmente impostato sugli Stati Uniti occidentali.

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"

Esempio in C#

La 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 . Se la sottoscrizione non è nell'area Stati Uniti occidentali, modificare il valore di FetchTokenUri in modo che corrisponda all'area della sottoscrizione.

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

Esempio in 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://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)

Come usare un token di accesso

Il token di accesso deve essere inviato al servizio come 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 Riconoscimento vocale per brevi audio:

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

Utilizzare Autenticazione Microsoft Entra

Per usare l'autenticazione di Microsoft Entra con l'API REST Riconoscimento vocale per brevi audio, è necessario creare un token di accesso. I passaggi per ottenere il token di accesso costituito da ID risorsa e token di accesso Microsoft Entra sono uguali a quando si usa Speech SDK. Seguire la procedura descritta qui Usare l'autenticazione di Microsoft Entra

  • Creare una risorsa Voce
  • Configurare la risorsa Voce per l'autenticazione di Microsoft Entra
  • Ottenere un token di accesso di Microsoft Entra
  • Ottenere l'ID della risorsa Voce

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 Riconoscimento vocale per brevi audio:

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

Per altre informazioni sui token di accesso di Microsoft Entra, inclusa la durata dei token, vedere Token di accesso in Microsoft Identity Platform.

Passaggi successivi