API REST de reconnaissance vocale pour audio court

Article
01/21/2024

Les cas d’usage de l’API REST de reconnaissance vocale pour l’audio court sont limités. Utilisez-la uniquement si vous ne pouvez pas utiliser le Kit de développement logiciel (SDK) Speech.

Avant d’utiliser l’API REST de reconnaissance vocale pour audio court, prenez conscience des limitations suivantes :

Les demandes qui utilisent l’API REST pour audio court et transmettent directement l’audio ne peuvent pas contenir plus de 60 secondes d’audio. Les formats audio d’entrée sont plus limités que le Kit de développement logiciel (SDK) de Speech.
L’API REST pour audio court retourne uniquement les résultats finaux. Elle ne fournit pas de résultats partiels.
La traduction vocale n’est pas prise en charge via l’API REST pour l’audio court. Vous devez utiliser le kit SDK Speech.
La transcription par lots et la reconnaissance vocale personnalisée ne sont pas prises en charge via l’API REST pour l’audio court. Vous devez toujours utiliser l’API REST Speech to text pour la transcription par lots et la reconnaissance vocale personnalisée.

Avant d’utiliser l’API REST de reconnaissance vocale, vous devez effectuer un échange de jetons dans le cadre de l’authentification pour accéder au service. Pour en savoir plus, consultez Authentification.

Régions et points de terminaison

Le point de terminaison de l’API REST pour audio court a le format suivant :

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

Remplacez <REGION_IDENTIFIER> par l’identificateur correspondant à la région de votre ressource Speech.

Remarque

Consultez cet article à propos des clouds souverains pour les points de terminaison Azure Government et Microsoft Azure géré par 21Vianet.

Formats audio

L’audio est envoyé dans le corps de la requête HTTP POST. Il doit être dans l’un des formats de ce tableau :

Format	Codec	Vitesse de transmission	Échantillonnage
WAV	PCM	256 Kbits/s	16 kHz, mono
OGG	OPUS	256 Kbits/s	16 kHz, mono

Notes

Les formats précédents sont pris en charge par le biais de l’API REST pour audio court et WebSocket dans le service Speech. Le SDK Speech prend en charge le format WAV avec codec PCM, ainsi que d’autres formats.

En-têtes de requête

Le tableau ci-dessous répertorie les en-têtes obligatoires et facultatifs pour les demandes de reconnaissance vocale :

En-tête	Description	Obligatoire ou facultatif
`Ocp-Apim-Subscription-Key`	Votre clé de ressource du service Speech.	Cet en-tête ou `Authorization` est requis.
`Authorization`	Un jeton d’autorisation précédé du mot `Bearer`. Pour en savoir plus, consultez Authentification.	Cet en-tête ou `Ocp-Apim-Subscription-Key` est requis.
`Pronunciation-Assessment`	Spécifie les paramètres pour l’indication des scores de prononciation dans les résultats de la reconnaissance. Ces scores évaluent la qualité de prononciation des entrées vocales, avec des indicateurs comme la précision, la fluidité et l’exhaustivité. Ce paramètre est un format JSON encodé en Base64 qui contient plusieurs paramètres détaillés. Pour découvrir comment créer cet en-tête, consultez Paramètres d’évaluation de la prononciation.	Facultatif
`Content-type`	Décrit le format et le codec des données audio fournies. Les valeurs acceptées sont `audio/wav; codecs=audio/pcm; samplerate=16000` et `audio/ogg; codecs=opus`.	Obligatoire
`Transfer-Encoding`	Spécifie que les données audio sont envoyées en bloc plutôt que dans un seul fichier. Utilisez cet en-tête uniquement si vous segmentez des données audio.	Facultatif
`Expect`	Si vous utilisez un transfert en bloc, envoyez `Expect: 100-continue`. Le service Speech reconnaît la demande initiale et attend davantage de données.	Obligatoire si vous envoyez des données audio en bloc.
`Accept`	Si cette valeur est fournie, elle doit être `application/json`. Le service Speech fournit les résultats au format JSON. Certains frameworks de demande fournissent une valeur par défaut incompatible. Il est recommandé de toujours inclure `Accept`.	Cette étape est facultative mais recommandée.

Paramètres de requête

Ces paramètres peuvent être inclus dans la chaîne de la requête REST.

Notes

Vous devez ajouter le paramètre de langue à l’URL pour éviter de recevoir une erreur HTTP 4xx. Par exemple, la langue définie sur la valeur Anglais (États-Unis) par le biais du point de terminaison USA Ouest est : https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Paramètre	Description	Obligatoire ou facultatif
`language`	Identifie la langue parlée en cours de reconnaissance. Voir Langues prises en charge.	Obligatoire
`format`	Spécifie le format du résultat. Les valeurs acceptées sont `simple` et `detailed`. Les résultats simples incluent `RecognitionStatus`, `DisplayText`, `Offset` et `Duration`. Les réponses détaillées incluent quatre représentations différentes du texte affiché. La valeur par défaut est `simple`.	Facultatif
`profanity`	Spécifie comment traiter la vulgarité dans les résultats de la reconnaissance. Les valeurs acceptées sont les suivantes : `masked`, qui remplace les termes vulgaires par des astérisques. `removed`, qui supprime tous les termes vulgaires des résultats. `raw`, qui inclut les termes vulgaires dans les résultats. La valeur par défaut est `masked`.	Facultatif
`cid`	Quand vous utilisez Speech Studio pour créer des modèles personnalisés, vous pouvez utiliser la valeur ID du point de terminaison de la page Déploiement. Utilisez la valeur ID du point de terminaison comme argument pour le paramètre de chaîne de requête `cid`.	Facultatif

Paramètres d’évaluation de la prononciation

Ce tableau liste les paramètres obligatoires et facultatifs pour l’évaluation de la prononciation :

Paramètre	Description	Obligatoire ou facultatif
`ReferenceText`	Texte duquel la prononciation est évaluée.	Requis
`GradingSystem`	Système de points pour la calibration du score. Le système `FivePoint` donne un score à virgule flottante de 0 à 5 et `HundredMark` donne un score à virgule flottante de 0 à 100. Par défaut : `FivePoint`.	Facultatif
`Granularity`	Granularité de l’évaluation. Les valeurs acceptées sont : `Phoneme`, qui indique le score aux niveaux du texte intégral, du mot et du phonème. `Word`, qui indique le score aux niveaux du texte intégral et du mot. `FullText`, qui indique le score au niveau du texte intégral uniquement. La valeur par défaut est `Phoneme`.	Facultatif
`Dimension`	Définit les critères de sortie. Les valeurs acceptées sont : `Basic`, qui indique le score de précision uniquement. `Comprehensive`, qui indique les scores sur plusieurs dimensions (par exemple, le score de fluidité et le score d’exhaustivité au niveau du texte intégral et le type d’erreur au niveau du mot). Pour voir les définitions des différentes dimensions de score et des types d’erreur de mot, consultez Propriétés de réponse. La valeur par défaut est `Basic`.	Facultatif
`EnableMiscue`	Active le calcul de faute de langue. Avec ce paramètre activé, les mots prononcés sont comparés au texte de référence. Elles sont marquées avec omission ou insertion en fonction de la comparaison. Les valeurs acceptées sont `False` et `True`. La valeur par défaut est `False`.	Facultatif
`ScenarioId`	GUID qui indique un système de point personnalisé.	Facultatif

Voici un exemple de code JSON qui contient les paramètres d’évaluation de la prononciation :

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

L’exemple de code suivant montre comment créer les paramètres d’évaluation de la prononciation dans l’en-tête Pronunciation-Assessment :

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

Nous recommandons vivement un chargement par streaming (transfert en bloc) quand vous publiez les données audio, ce qui peut réduire considérablement la latence. Pour découvrir comment activer le streaming, consultez l’exemple de code dans différents langages de programmation.

Notes

Pour plus d’informations, consultez Évaluation de la prononciation.

Exemple de requête

L’exemple suivant comprend le nom d’hôte et les en-têtes obligatoires. Il est important de noter que le service attend également des données audio, qui ne sont pas incluses dans cet exemple. Comme mentionné précédemment, l’envoi en bloc est recommandé, mais pas obligatoire.

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

Pour activer l’évaluation de la prononciation, vous pouvez ajouter l’en-tête suivant. Pour découvrir comment créer cet en-tête, consultez Paramètres d’évaluation de la prononciation.

Pronunciation-Assessment: eyJSZWZlcm...

Codes d’état HTTP

Le code d’état HTTP de chaque réponse indique la réussite ou des erreurs courantes.

Code d'état HTTP	Description	Causes possibles
100	Suite	La demande initiale est acceptée. Passez à l’envoi du reste des données. (Ce code est utilisé avec le transfert en bloc.)
200	OK	La demande a abouti. Le corps de la réponse est un objet JSON.
400	Demande incorrecte	Le code de la langue n’a pas été fourni, la langue n’est pas prise en charge ou le fichier audio n’est pas valide (par exemple).
401	Non autorisé	Une clé de ressource ou un jeton d’autorisation n’est pas valide dans la région spécifiée, ou bien un point de terminaison n’est pas valide.
403	Interdit	Il manque une clé de ressource ou un jeton d’autorisation.

Exemples de réponses

Voici une réponse classique pour une reconnaissance simple :

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

Voici une réponse classique pour une reconnaissance 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"
    }
  ]
}

Voici une réponse classique pour une reconnaissance avec évaluation de la prononciation :

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

Propriétés de la réponse

Les résultats sont fournis au format JSON. Le format simple inclut les champs généraux suivants :

Propriété	Description
`RecognitionStatus`	État, tel que `Success` pour une reconnaissance ayant réussi. Consultez le tableau suivant.
`DisplayText`	Texte reconnu après application de la capitalisation, de la ponctuation, de la normalisation de texte inversée et du masquage des vulgarités. Présent uniquement en cas de réussite. La normalisation de texte inversée correspond à la conversion du texte parlé en formes plus courtes, comme 200 pour « deux cents » ou « Dr Dupont » pour « Docteur Dupont ».
`Offset`	Moment (en unités de 100 nanosecondes) à partir duquel la voix identifiée commence dans le flux audio.
`Duration`	Durée (en unités de 100 nanosecondes) de la voix reconnue dans le flux audio.

Le champ RecognitionStatus peut contenir ces valeurs :

État	Description
`Success`	La reconnaissance a réussi et le champ `DisplayText` est présent.
`NoMatch`	Des paroles ont été détectées dans le flux audio, mais aucun mot de la langue cible n’a été mis en correspondance. Cet état signifie généralement que la langue de reconnaissance est différente de celle que l’utilisateur parle.
`InitialSilenceTimeout`	Le début du flux audio contenait uniquement un silence, et le service a dépassé son délai d’attente de paroles.
`BabbleTimeout`	Le début du flux audio contenait uniquement du bruit, et le service a dépassé son délai d’attente de paroles.
`Error`	Le service de reconnaissance a rencontré une erreur interne et n’a pas pu continuer. Réessayez si possible.

Notes

Si l’audio est composé uniquement de grossièretés et que le paramètre de requête profanity a la valeur remove, le service ne retourne pas de résultat de reconnaissance vocale.

Le detailed format inclut davantage de formes de résultats reconnus. Lorsque vous utilisez le format detailed, DisplayText est fourni en tant que Display pour chaque résultat dans la liste NBest.

L’objet dans la liste NBest peut inclure :

Propriété	Description
`Confidence`	Score de confiance de l’entrée, compris entre 0,0 (confiance nulle) et 1,0 (confiance totale).
`Lexical`	La forme lexicale du texte reconnu : les mots reconnus.
`ITN`	Forme ITN (normalisation de texte inversée) ou canonique du texte reconnu, avec numéros de téléphone, chiffres, abréviations (« docteur smith » devient « dr smith ») et autres transformations appliquées.
`MaskedITN`	La forme « normalisation du texte inversée » avec masquage des grossièretés appliqué, si nécessaire.
`Display`	La forme d’affichage du texte reconnu, avec signes de ponctuation et mise en majuscules ajoutés. Ce paramètre est le même que celui que `DisplayText` fournit lorsque le format est défini sur `simple`.
`AccuracyScore`	Précision de prononciation du discours. La précision indique dans quelle mesure les phonèmes correspondent à la prononciation d’un intervenant de langue maternelle. Le score de précision aux niveaux du mot et du texte intégral est agrégé à partir du score de précision au niveau du phonème.
`FluencyScore`	Fluidité de la parole fournie. La fluidité indique dans quelle mesure le discours correspond à l’utilisation qu’un orateur de langue maternelle fait des pauses entre les mots.
`CompletenessScore`	Intégralité du discours, déterminée par le calcul du rapport entre les mots prononcés et l’entrée de texte de référence.
`PronScore`	Score global qui indique la qualité de la prononciation de la parole fournie. Ce score est agrégé à partir de `AccuracyScore`, `FluencyScore` et `CompletenessScore` avec une pondération.
`ErrorType`	Cette valeur indique si un mot est omis, inséré ou mal prononcé, par rapport à `ReferenceText`. Les valeurs possibles sont `None` (aucune erreur sur ce mot), `Omission`, `Insertion` et `Mispronunciation`.

Transfert en bloc

Le transfert en bloc (Transfer-Encoding: chunked) peut aider à réduire la latence de la reconnaissance. Il permet au service Speech de commencer à traiter le fichier audio pendant sa transmission. L’API REST pour l’audio court ne fournit pas de résultats partiels ou intermédiaires.

L’exemple de code suivant montre comment envoyer de l’audio en bloc. Seul le premier segment doit contenir l’en-tête du fichier audio. request est un objet HttpWebRequest connecté au point de terminaison REST approprié. audioFile est le chemin vers un fichier audio sur disque.

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

Chaque requête nécessite un en-tête d’autorisation. Ce tableau présente les en-têtes pris en charge pour chaque fonctionnalité :

En-têtes d’autorisation pris en charge	Reconnaissance vocale	Synthèse vocale
`Ocp-Apim-Subscription-Key`	Oui	Oui
`Authorization: Bearer`	Oui	Oui

Quand vous utilisez l’en-tête Ocp-Apim-Subscription-Key, vous devez uniquement fournir votre clé de ressource. Par exemple :

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

Lorsque vous utilisez l’en-tête Authorization: Bearer, vous devez envoyer une demande au point de terminaison issueToken. Dans cette requête, vous échangez votre clé de ressource contre un jeton d’accès valide pendant 10 minutes.

Obtenir un jeton d’accès

Pour obtenir un jeton d’accès, vous avez besoin d’envoyer une demande au point de terminaison issueToken à l’aide de Ocp-Apim-Subscription-Key et de votre clé de ressource.

Le format du point de terminaison issueToken est le suivant :

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

Remplacez <REGION_IDENTIFIER> par l’identificateur correspondant à la région de votre abonnement.

Utilisez les exemples suivants pour créer votre demande de jeton d’accès.

Exemple HTTP

Cet exemple est une simple requête HTTP pour obtenir un jeton. Remplacez YOUR_SUBSCRIPTION_KEY par votre clé de ressource du service Speech. Si votre abonnement n’est pas dans la région USA Ouest, remplacez l’en-tête Host par le nom d’hôte de votre région.

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

Le corps de la réponse contient le jeton d’accès au format JSON Web Token (JWT).

Exemple de code PowerShell

Cet exemple est un simple script PowerShell pour obtenir un jeton d’accès. Remplacez YOUR_SUBSCRIPTION_KEY par votre clé de ressource du service Speech. Veillez à utiliser le point de terminaison correct pour la région correspondant à votre abonnement. Cet exemple est actuellement configuré pour l’USA Ouest.

$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

Exemple cURL

cURL est un outil en ligne de commande disponible dans Linux (ainsi que dans le sous-système Windows pour Linux). Cette commande cURL montre comment obtenir un jeton d’accès. Remplacez YOUR_SUBSCRIPTION_KEY par votre clé de ressource du service Speech. Veillez à utiliser le point de terminaison correct pour la région correspondant à votre abonnement. Cet exemple est actuellement configuré pour l’USA Ouest.

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"

Exemple de code C#

La classe C# montre comment obtenir un jeton d’accès. Transmettez votre clé de ressource du service Speech quand vous instanciez la classe. Si votre abonnement ne figure pas dans la région USA Ouest, modifiez la valeur FetchTokenUri afin qu’elle corresponde à la région de votre abonnement.

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

Exemple de code 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)

Utiliser un jeton d’accès

Le jeton d’accès doit être envoyé au service en tant qu’en-tête Authorization: Bearer <TOKEN>. Chaque jeton d’accès est valide pour une durée de 10 minutes. Vous pouvez à tout moment obtenir un nouveau jeton, mais pour réduire la latence et le trafic réseau, nous recommandons d’utiliser le même jeton pendant neuf minutes.

Voici un exemple de requête HTTP adressée à l’API REST de reconnaissance vocale pour audio court :

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

API REST de reconnaissance vocale pour audio court

Régions et points de terminaison

Formats audio

En-têtes de requête

Paramètres de requête

Paramètres d’évaluation de la prononciation

Exemple de requête

Codes d’état HTTP

Exemples de réponses

Propriétés de la réponse

Transfert en bloc

Authentication

Obtenir un jeton d’accès

Exemple HTTP

Exemple de code PowerShell

Exemple cURL

Exemple de code C#

Exemple de code Python

Utiliser un jeton d’accès

Étapes suivantes

Ressources supplémentaires