Partager via


API REST de reconnaissance vocale pour audio court

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

Lorsque vous utilisez l’en-tête Ocp-Apim-Subscription-Key , seule votre clé de ressource doit être fournie. Par exemple :

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

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

Une autre option consiste à utiliser l’authentification Microsoft Entra qui utilise également l’en-tête Authorization: Bearer , mais avec un jeton émis via l’ID Microsoft Entra. Consultez Utiliser l’authentification Microsoft Entra.

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

Utiliser Authentification Microsoft Entra

Pour utiliser l’authentification Microsoft Entra avec l’API REST Speech to text pour un audio court, vous devez créer un jeton d’accès. Les étapes d’obtention du jeton d’accès constitué de l’ID de ressource et du jeton d’accès Microsoft Entra sont les mêmes que lors de l’utilisation du Kit de développement logiciel (SDK) Speech. Suivez les étapes ci-dessous pour utiliser l’authentification Microsoft Entra

  • Créer une ressource Speech
  • Configurer la ressource Speech pour l’authentification Microsoft Entra
  • Obtenir un jeton d’accès Microsoft Entra
  • Obtenir l’ID de ressource Speech

Une fois que l’ID de ressource et le jeton d’accès Microsoft Entra ont été obtenus, le jeton d’accès réel peut être construit au format suivant :

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Vous devez inclure le préfixe « aad# » et le séparateur « # » (hachage) entre l’ID de ressource et le jeton d’accès.

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

Pour en savoir plus sur les jetons d’accès Microsoft Entra, notamment leur durée de vie, consultez Jetons d’accès de la plateforme d’identités Microsoft.

Étapes suivantes