API REST de reconnaissance vocaleSpeech-to-text REST API

La reconnaissance vocale utilise deux API REST distinctes.Speech-to-text has two different REST APIs. Chaque API remplit son objectif particulier et utilise différents ensembles de points de terminaison.Each API serves its special purpose and uses different sets of endpoints.

Les API REST de reconnaissance vocale sont les suivantes :The Speech-to-text REST APIs are:

API REST de reconnaissance vocale v3.0Speech-to-text REST API v3.0

L’API REST de reconnaissance vocale v3.0 est utilisée pour la Transcription par lot et Custom Speech.Speech-to-text REST API v3.0 is used for Batch transcription and Custom Speech. Si vous avez besoin de communiquer avec une transcription en ligne via REST, utilisez l’API REST de reconnaissance vocale pour audio court.If you need to communicate with the OnLine transcription via REST, use Speech-to-text REST API for short audio.

Utilisez l’API REST v3.0 pour effectuer les tâches suivantes :Use REST API v3.0 to:

  • Copier des modèles vers d’autres abonnements si vous souhaitez que les collègues aient accès à un modèle que vous avez créé, ou si vous souhaitez déployer un modèle dans plusieurs régions.Copy models to other subscriptions in case you want colleagues to have access to a model you built, or in cases where you want to deploy a model to more than one region
  • Transcrire les données d’un conteneur (transcription en bloc) et fournir plusieurs URL de fichiers audio.Transcribe data from a container (bulk transcription) as well as provide multiple audio file URLs
  • Charger des données à partir de comptes de stockage Azure à l’aide d’un Uri de SAP.Upload data from Azure Storage accounts through the use of a SAS Uri
  • Obtenir des journaux par point de terminaison si les journaux ont été demandés pour celui-ci.Get logs per endpoint if logs have been requested for that endpoint
  • Demander le manifeste des modèles que vous créez, afin de configurer des conteneurs locaux.Request the manifest of the models you create, for the purpose of setting up on-premises containers

L’API REST v3.0 comprend des fonctionnalités telles que les suivantes :REST API v3.0 includes such features as:

  • Notifications de Webhook : tous les processus en cours d’exécution du service prennent désormais en charge les notifications de Webhook.Notifications-Webhooks—All running processes of the service now support webhook notifications. L’API REST v3.0 fournit les appels pour vous permettre d’inscrire vos webhooks à l’endroit où les notifications sont envoyées.REST API v3.0 provides the calls to enable you to register your webhooks where notifications are sent
  • Mise à jour de modèles derrière des points de terminaisonUpdating models behind endpoints
  • Adaptation de modèle avec plusieurs jeux de données : adaptez un modèle à l’aide de plusieurs combinaisons de jeux de données acoustiques, linguistiques et de prononciation.Model adaptation with multiple data sets—Adapt a model using multiple data set combinations of acoustic, language, and pronunciation data
  • Apportez votre propre de stockage : utilisez vos propres comptes de stockage pour les journaux, les fichiers de transcription et les autres données.Bring your own storage—Use your own storage accounts for logs, transcription files, and other data

Pour obtenir des exemples d’utilisation de l’API REST v3.0 avec la transcription par lot, consultez cet article.See examples on using REST API v3.0 with the Batch transcription is this article.

Si vous utilisez l’API REST de reconnaissance vocale v2.0, découvrez comment migrer vers la version v3.0 dans ce guide.If you are using Speech-to-text REST API v2.0, see how you can migrate to v3.0 in this guide.

Consultez les informations de référence complètes sur l’API REST de reconnaissance vocale v3.0 ici.See the full Speech-to-text REST API v3.0 Reference here.

API REST de reconnaissance vocale pour audio courtSpeech-to-text REST API for short audio

En guise d’alternative au Kit de développement logiciel (SDK), le service Speech vous permet de convertir la parole en texte à l’aide d’une API REST.As an alternative to the Speech SDK, the Speech service allows you to convert Speech-to-text using a REST API. Chaque point de terminaison accessible est associé à une région.Each accessible endpoint is associated with a region. Votre application nécessite une clé d’abonnement pour le point de terminaison que vous prévoyez d’utiliser.Your application requires a subscription key for the endpoint you plan to use. L’API REST pour audio court étant très limitée, elle ne doit être utilisée que dans les cas où le Kit de développement logiciel (SDK) Speech ne peut pas l’être.The REST API for short audio is very limited, and it should only be used in cases were the Speech SDK cannot.

Avant d’utiliser l’API REST de reconnaissance vocale pour audio court, prenez en compte les aspects suivants :Before using the Speech-to-text REST API for short audio, consider the following:

  • 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.Requests that use the REST API for short audio and transmit audio directly can only contain up to 60 seconds of audio.
  • L’API REST de reconnaissance vocale pour audio court retourne uniquement des résultats finaux.The Speech-to-text REST API for short audio only returns final results. Les résultats partiels ne sont pas fournis.Partial results are not provided.

Si vous devez envoyer un contenu audio plus long pour votre application, vous pouvez utiliser le Kit de développement logiciel (SDK) Speech ou l’API REST de reconnaissance vocale v3.0.If sending longer audio is a requirement for your application, consider using the Speech SDK or Speech-to-text REST API v3.0.

Sugerencia

Consultez cet article pour les points de terminaison Azure Government et Azure Chine.See this article for Azure Government and Azure China endpoints.

AuthenticationAuthentication

Chaque requête nécessite un en-tête d’autorisation.Each request requires an authorization header. Ce tableau présente les en-têtes pris en charge pour chaque service :This table illustrates which headers are supported for each service:

En-têtes d'autorisation pris en chargeSupported authorization headers Reconnaissance vocaleSpeech-to-text Synthèse vocaleText-to-speech
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key OuiYes OuiYes
Autorisation : BearerAuthorization: Bearer OuiYes OuiYes

Lorsque vous utilisez l’en-tête Ocp-Apim-Subscription-Key, vous devez uniquement fournir votre clé d’abonnement.When using the Ocp-Apim-Subscription-Key header, you're only required to provide your subscription key. Par exemple :For example:

'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.When using the Authorization: Bearer header, you're required to make a request to the issueToken endpoint. Dans cette requête, vous échangez votre clé d’abonnement contre un jeton d’accès valide pendant 10 minutes.In this request, you exchange your subscription key for an access token that's valid for 10 minutes. Dans les sections suivantes, vous apprendrez à obtenir et utiliser un jeton.In the next few sections you'll learn how to get a token, and use a token.

Obtenir un jeton d’accèsHow to get an access token

Pour obtenir un jeton d’accès, vous devrez envoyer une demande au point de terminaison issueToken à l’aide de Ocp-Apim-Subscription-Key et de votre clé d’abonnement.To get an access token, you'll need to make a request to the issueToken endpoint using the Ocp-Apim-Subscription-Key and your subscription key.

Le format du point de terminaison issueToken est le suivant :The issueToken endpoint has this format:

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

Remplacez <REGION_IDENTIFIER> par l’identificateur correspondant à la région de votre abonnement dans le tableau suivant :Replace <REGION_IDENTIFIER> with the identifier matching the region of your subscription from this table:

GeographyGeography RégionRegion Identificateur de la régionRegion identifier
AmériqueAmericas USA CentreCentral US centralus
AmériqueAmericas USA EstEast US eastus
AmériqueAmericas USA Est 2East US 2 eastus2
AmériqueAmericas Centre-Nord des États-UnisNorth Central US northcentralus
AmériqueAmericas États-Unis - partie centrale méridionaleSouth Central US southcentralus
AmériqueAmericas Centre-USA OuestWest Central US westcentralus
AmériqueAmericas USA OuestWest US westus
AmériqueAmericas USA Ouest 2West US 2 westus2
AmériqueAmericas Centre du CanadaCanada Central canadacentral
AmériqueAmericas Brésil SudBrazil South brazilsouth
Asie-PacifiqueAsia Pacific Asie EstEast Asia eastasia
Asie-PacifiqueAsia Pacific Asie Sud-EstSoutheast Asia southeastasia
Asie-PacifiqueAsia Pacific Australie EstAustralia East australiaeast
Asie-PacifiqueAsia Pacific Inde centraleCentral India centralindia
Asie-PacifiqueAsia Pacific Japon EstJapan East japaneast
Asie-PacifiqueAsia Pacific OuJapon EstJapan West japanwest
Asie-PacifiqueAsia Pacific Centre de la CoréeKorea Central koreacentral
EuropeEurope Europe NordNorth Europe northeurope
EuropeEurope Europe OuestWest Europe westeurope
EuropeEurope France CentreFrance Central francecentral
EuropeEurope Sud du Royaume-UniUK South uksouth

Utilisez ces exemples pour créer votre demande de jeton d’accès.Use these samples to create your access token request.

Exemple HTTPHTTP sample

Cet exemple est une simple requête HTTP pour obtenir un jeton.This example is a simple HTTP request to get a token. Remplacez YOUR_SUBSCRIPTION_KEY par votre clé d’abonnement de service de reconnaissance vocale.Replace YOUR_SUBSCRIPTION_KEY with your Speech Service subscription key. 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.If your subscription isn't in the West US region, replace the Host header with your region's host name.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: westus.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).The body of the response contains the access token in JSON Web Token (JWT) format.

Exemple de code PowerShellPowerShell sample

Cet exemple est un simple script PowerShell pour obtenir un jeton d’accès.This example is a simple PowerShell script to get an access token. Remplacez YOUR_SUBSCRIPTION_KEY par votre clé d’abonnement de service de reconnaissance vocale.Replace YOUR_SUBSCRIPTION_KEY with your Speech Service subscription key. Veillez à utiliser le point de terminaison correct pour la région correspondant à votre abonnement.Make sure to use the correct endpoint for the region that matches your subscription. Cet exemple est actuellement configuré pour l’USA Ouest.This example is currently set to West US.

$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://westus.api.cognitive.microsoft.com/sts/v1.0/issueToken
 -Headers $FetchTokenHeader

# show the token received
$OAuthToken

Exemple cURLcURL sample

cURL est un outil en ligne de commande disponible dans Linux (ainsi que dans le sous-système Windows pour Linux).cURL is a command-line tool available in Linux (and in the Windows Subsystem for Linux). Cette commande cURL montre comment obtenir un jeton d’accès.This cURL command illustrates how to get an access token. Remplacez YOUR_SUBSCRIPTION_KEY par votre clé d’abonnement de service de reconnaissance vocale.Replace YOUR_SUBSCRIPTION_KEY with your Speech Service subscription key. Veillez à utiliser le point de terminaison correct pour la région correspondant à votre abonnement.Make sure to use the correct endpoint for the region that matches your subscription. Cet exemple est actuellement configuré pour l’USA Ouest.This example is currently set to West US.

curl -v -X POST \
 "https://westus.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#C# sample

La classe C# montre comment obtenir un jeton d’accès.This C# class illustrates how to get an access token. Transmettez votre clé d’abonnement du service Speech quand vous instanciez la classe.Pass your Speech Service subscription key when you instantiate the class. 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.If your subscription isn't in the West US region, change the value of FetchTokenUri to match the region for your subscription.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://westus.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 PythonPython sample

# 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://westus.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èsHow to use an access token

Le jeton d’accès doit être envoyé au service en tant qu’en-tête Authorization: Bearer <TOKEN>.The access token should be sent to the service as the Authorization: Bearer <TOKEN> header. Chaque jeton d’accès est valide pour une durée de 10 minutes.Each access token is valid for 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 durant neuf minutes.You can get a new token at any time, however, to minimize network traffic and latency, we recommend using the same token for nine minutes.

Voici un exemple de requête HTTP adressée à l’API REST de reconnaissance vocale pour audio court :Here's a sample HTTP request to the Speech-to-text REST API for short 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...

Régions et points de terminaisonRegions and endpoints

Le point de terminaison de l’API REST pour audio court a le format suivant :The endpoint for the REST API for short audio has this format:

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

Remplacez <REGION_IDENTIFIER> par l'identificateur correspondant à la région de votre abonnement dans le tableau suivant :Replace <REGION_IDENTIFIER> with the identifier matching the region of your subscription from this table:

GeographyGeography RégionRegion Identificateur de la régionRegion identifier
AmériqueAmericas USA CentreCentral US centralus
AmériqueAmericas USA EstEast US eastus
AmériqueAmericas USA Est 2East US 2 eastus2
AmériqueAmericas Centre-Nord des États-UnisNorth Central US northcentralus
AmériqueAmericas États-Unis - partie centrale méridionaleSouth Central US southcentralus
AmériqueAmericas Centre-USA OuestWest Central US westcentralus
AmériqueAmericas USA OuestWest US westus
AmériqueAmericas USA Ouest 2West US 2 westus2
AmériqueAmericas Centre du CanadaCanada Central canadacentral
AmériqueAmericas Brésil SudBrazil South brazilsouth
Asie-PacifiqueAsia Pacific Asie EstEast Asia eastasia
Asie-PacifiqueAsia Pacific Asie Sud-EstSoutheast Asia southeastasia
Asie-PacifiqueAsia Pacific Australie EstAustralia East australiaeast
Asie-PacifiqueAsia Pacific Inde centraleCentral India centralindia
Asie-PacifiqueAsia Pacific Japon EstJapan East japaneast
Asie-PacifiqueAsia Pacific OuJapon EstJapan West japanwest
Asie-PacifiqueAsia Pacific Centre de la CoréeKorea Central koreacentral
EuropeEurope Europe NordNorth Europe northeurope
EuropeEurope Europe OuestWest Europe westeurope
EuropeEurope France CentreFrance Central francecentral
EuropeEurope Sud du Royaume-UniUK South uksouth

Nota

Le paramètre de langue doit être ajouté à l'URL pour éviter de recevoir une erreur HTTP 4xx.The language parameter must be appended to the URL to avoid receiving an 4xx HTTP error. Par exemple, la langue définie sur la valeur Anglais (États-Unis) à l’aide du point de terminaison USA Ouest est : https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.For example, the language set to US English using the West US endpoint is: https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

Paramètres de requêteQuery parameters

Ces paramètres peuvent être inclus dans la chaîne de la requête REST.These parameters may be included in the query string of the REST request.

ParamètreParameter DescriptionDescription Obligatoire/facultatifRequired / Optional
language Identifie la langue parlée qui est reconnue.Identifies the spoken language that is being recognized. Voir Langues prises en charge.See Supported languages. ObligatoireRequired
format Spécifie le format du résultat.Specifies the result format. Les valeurs acceptées sont simple et detailed.Accepted values are simple and detailed. Les résultats simples incluent RecognitionStatus, DisplayText, Offset et Duration.Simple results include RecognitionStatus, DisplayText, Offset, and Duration. Les réponses détaillées incluent quatre représentations différentes du texte affiché.Detailed responses include four different representations of display text. La valeur par défaut est simple.The default setting is simple. FacultatifOptional
profanity Spécifie comment traiter la vulgarité dans les résultats de la reconnaissance.Specifies how to handle profanity in recognition results. Les valeurs acceptées sont masked, qui remplace les vulgarités par des astérisques, removed, qui supprime les vulgarités du résultat, ou raw, qui inclut les vulgarités dans le résultat.Accepted values are masked, which replaces profanity with asterisks, removed, which removes all profanity from the result, or raw, which includes the profanity in the result. La valeur par défaut est masked.The default setting is masked. FacultatifOptional
cid Lorsque vous utilisez le portail Custom Speech pour créer des modèles personnalisés, vous pouvez utiliser des modèles personnalisés à l’aide de leur ID de point de terminaison figurant sur la page Déploiement.When using the Custom Speech portal to create custom models, you can use custom models via their Endpoint ID found on the Deployment page. Utilisez l’ID de point de terminaison comme argument pour le paramètre de chaîne de requête cid.Use the Endpoint ID as the argument to the cid query string parameter. FacultatifOptional

En-têtes de requêteRequest headers

Ce tableau répertorie les en-têtes obligatoires et facultatifs pour les demandes de reconnaissance vocale.This table lists required and optional headers for Speech-to-text requests.

En-têteHeader DescriptionDescription Obligatoire/facultatifRequired / Optional
Ocp-Apim-Subscription-Key Votre clé d’abonnement du service Speech.Your Speech service subscription key. Cet en-tête ou Authorization est requis.Either this header or Authorization is required.
Authorization Un jeton d’autorisation précédé du mot Bearer.An authorization token preceded by the word Bearer. Pour en savoir plus, consultez Authentification.For more information, see Authentication. Cet en-tête ou Ocp-Apim-Subscription-Key est requis.Either this header or Ocp-Apim-Subscription-Key is required.
Pronunciation-Assessment Spécifie les paramètres pour montrer les scores de prononciation dans les résultats de la reconnaissance, qui évaluent la qualité de la prononciation des entrées vocales, avec des indicateurs de justesse, d’aisance, d’exhaustivité, etc. Ce paramètre est un format JSON encodé en base64 contenant plusieurs paramètres détaillés.Specifies the parameters for showing pronunciation scores in recognition results, which assess the pronunciation quality of speech input, with indicators of accuracy, fluency, completeness, etc. This parameter is a base64 encoded json containing multiple detailed parameters. Pour plus d’informations sur la création de cet en-tête, consultez Paramètres d’évaluation de la prononciation.See Pronunciation assessment parameters for how to build this header. FacultatifOptional
Content-type Décrit le format et le codec des données audio fournies.Describes the format and codec of the provided audio data. Les valeurs acceptées sont audio/wav; codecs=audio/pcm; samplerate=16000 et audio/ogg; codecs=opus.Accepted values are audio/wav; codecs=audio/pcm; samplerate=16000 and audio/ogg; codecs=opus. ObligatoireRequired
Transfer-Encoding Spécifie que les données audio sont envoyées en bloc plutôt que dans un seul fichier.Specifies that chunked audio data is being sent, rather than a single file. Utilisez uniquement cet en-tête si vous envoyez les données audio en bloc.Only use this header if chunking audio data. FacultatifOptional
Expect Si vous utilisez le transfert en bloc, envoyez Expect: 100-continue.If using chunked transfer, send Expect: 100-continue. Le service Speech accuse réception de la requête initiale et attend des données supplémentaires.The Speech service acknowledges the initial request and awaits additional data. Requis si vous envoyez les données audio en bloc.Required if sending chunked audio data.
Accept Si cette valeur est fournie, elle doit être application/json.If provided, it must be application/json. Le service Speech fournit les résultats au format JSON.The Speech service provides results in JSON. Certains frameworks de demande fournissent une valeur par défaut incompatible.Some request frameworks provide an incompatible default value. Il est recommandé de toujours inclure Accept.It is good practice to always include Accept. Cette étape est facultative mais recommandée.Optional, but recommended.

Formats audioAudio formats

L’audio est envoyé dans le corps de la requête HTTP POST.Audio is sent in the body of the HTTP POST request. Il doit être dans l’un des formats de ce tableau :It must be in one of the formats in this table:

FormatFormat CodecCodec Vitesse de transmissionBit rate ÉchantillonnageSample Rate
WAVWAV PCMPCM 256 Kbits/s256 kbps 16 kHz, mono16 kHz, mono
OGGOGG OPUSOPUS 256 Kbits/s256 kpbs 16 kHz, mono16 kHz, mono

Nota

Les formats ci-dessus sont pris en charge via l’API REST pour audio court et WebSocket dans le service Speech.The above formats are supported through REST API for short audio and WebSocket in the Speech service. Pour le moment, le kit de développement logiciel (SDK) Speech prend en charge le format WAV avec codec PCM, ainsi que d'autres formats.The Speech SDK currently supports the WAV format with PCM codec as well as other formats.

Paramètres d’évaluation de la prononciationPronunciation assessment parameters

Ce tableau liste les paramètres obligatoires et facultatifs pour l’évaluation de la prononciation.This table lists required and optional parameters for pronunciation assessment.

ParamètreParameter DescriptionDescription Requis ?Required?
ReferenceTextReferenceText Texte duquel la prononciation est évaluée.The text that the pronunciation will be evaluated against. ObligatoireRequired
GradingSystemGradingSystem Système de points pour la calibration du score.The point system for score calibration. Le système FivePoint donne un score à virgule flottante de 0 à 5 et HundredMark donne un score à virgule flottante de 0 à 100.The FivePoint system gives a 0-5 floating point score, and HundredMark gives a 0-100 floating point score. Par défaut : FivePoint.Default: FivePoint. FacultatifOptional
GranularitéGranularity Granularité de l’évaluation.The evaluation granularity. Les valeurs acceptées sont Phoneme, qui affiche le score au niveau du texte intégral, du mot et du phonème, Word, qui affiche le score au niveau du texte intégral et du mot, FullText, qui affiche le score au niveau du texte intégral uniquement.Accepted values are Phoneme, which shows the score on the full text, word and phoneme level, Word, which shows the score on the full text and word level, FullText, which shows the score on the full text level only. La valeur par défaut est Phoneme.The default setting is Phoneme. FacultatifOptional
DimensionDimension Définit les critères de sortie.Defines the output criteria. Les valeurs acceptées sont Basic, qui affiche uniquement le score de justesse, Comprehensive affiche des scores sur davantage de dimensions (par exemple, le score d’aisance et le score d’exhaustivité au niveau du texte intégral, du type d’erreur et du mot).Accepted values are Basic, which shows the accuracy score only, Comprehensive shows scores on more dimensions (e.g. fluency score and completeness score on the full text level, error type on word level). Consultez les paramètres de réponse pour voir les définitions des différentes dimensions de score et des types d’erreur de mot.Check Response parameters to see definitions of different score dimensions and word error types. La valeur par défaut est Basic.The default setting is Basic. FacultatifOptional
EnableMiscueEnableMiscue Active le calcul de faute de langue.Enables miscue calculation. Quand cette option est activée, les mots prononcés sont comparés au texte de référence et sont marqués comme omission/insertion en fonction de la comparaison.With this enabled, the pronounced words will be compared to the reference text, and will be marked with omission/insertion based on the comparison. Les valeurs acceptées sont False et True.Accepted values are False and True. La valeur par défaut est False.The default setting is False. FacultatifOptional
ScenarioIdScenarioId GUID indiquant un système de points personnalisé.A GUID indicating a customized point system. FacultatifOptional

Voici un exemple de code JSON contenant les paramètres d’évaluation de la prononciation :Below is an example JSON containing the pronunciation assessment parameters:

{
  "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 :The following sample code shows how to build the pronunciation assessment parameters into the Pronunciation-Assessment header:

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) lors de la publication des données audio, ce qui peut réduire considérablement la latence.We strongly recommend streaming (chunked) uploading while posting the audio data, which can significantly reduce the latency. Consultez exemple de code dans différents langages de programmation pour voir comment activer le streaming.See sample code in different programming languages for how to enable streaming.

Nota

La fonctionnalité d’évaluation de la prononciation est actuellement disponible uniquement dans les régions westus, eastasia et centralindia.The pronunciation assessment feature is currently only available on westus, eastasia and centralindia regions. Par ailleurs, cette fonctionnalité n’est pour le moment disponible que dans la langue en-US.And this feature is currently only available on en-US language.

Exemple de requêteSample request

L’exemple ci-dessous inclut le nom d’hôte et les en-têtes requis.The sample below includes the hostname and required headers. Il est important de noter que le service attend également des données audio, ce qui n’est pas inclus dans cet exemple.It's important to note that the service also expects audio data, which is not included in this sample. Comme mentionné précédemment, l’envoi en bloc est recommandé, mais pas nécessaire.As mentioned earlier, chunking is recommended, however, not required.

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_SUBSCRIPTION_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 ci-dessous.To enable pronunciation assessment, you can add below header. Pour plus d’informations sur la création de cet en-tête, consultez Paramètres d’évaluation de la prononciation.See Pronunciation assessment parameters for how to build this header.

Pronunciation-Assessment: eyJSZWZlcm...

Codes d’état HTTPHTTP status codes

Le code d’état HTTP de chaque réponse indique la réussite ou des erreurs courantes.The HTTP status code for each response indicates success or common errors.

Code d'état HTTPHTTP status code DescriptionDescription Raison possiblePossible reason
100 ContinueContinue La requête initiale a été acceptée.The initial request has been accepted. Passez à l’envoi du reste des données.Proceed with sending the rest of the data. (Utilisé avec le transfert en bloc)(Used with chunked transfer)
200 OKOK La requête a réussi ; le corps de réponse est un objet JSON.The request was successful; the response body is a JSON object.
400 Demande incorrecteBad request Le code de langue n’est pas fourni, la langue n’est pas prise en charge, le fichier audio est non valide, etc.Language code not provided, not a supported language, invalid audio file, etc.
401 Non autoriséUnauthorized La clé d’abonnement ou le jeton d’autorisation n’est pas valide dans la région spécifiée, ou le point de terminaison n’est pas valide.Subscription key or authorization token is invalid in the specified region, or invalid endpoint.
403 InterditForbidden Clé d’abonnement ou jeton d’autorisation manquant.Missing subscription key or authorization token.

Transfert en blocChunked transfer

Le transfert en bloc (Transfer-Encoding: chunked) peut aider à réduire la latence de la reconnaissance.Chunked transfer (Transfer-Encoding: chunked) can help reduce recognition latency. Il permet au service Speech de commencer à traiter le fichier audio pendant sa transmission.It allows the Speech service to begin processing the audio file while it is transmitted. L’API REST pour audio court ne fournit pas de résultats partiels ou intermédiaires.The REST API for short audio does not provide partial or interim results.

Cet exemple de code montre comment envoyer l’audio en bloc.This code sample shows how to send audio in chunks. Seul le premier segment doit contenir l’en-tête du fichier audio.Only the first chunk should contain the audio file's header. request est un objet HttpWebRequest connecté au point de terminaison REST approprié.request is an HttpWebRequest object connected to the appropriate REST endpoint. audioFile est le chemin vers un fichier audio sur disque.audioFile is the path to an audio file on disk.

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_SUBSCRIPTION_KEY";
request.AllowWriteStreamBuffering = false;

using (var fs = new FileStream(audioFile, FileMode.Open, FileAccess.Read))
{
    // Open a request stream and write 1024 byte chunks in the stream one at a time.
    byte[] buffer = null;
    int bytesRead = 0;
    using (var requestStream = request.GetRequestStream())
    {
        // Read 1024 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();
    }
}

Paramètres de réponseResponse parameters

Les résultats sont fournis au format JSON.Results are provided as JSON. Le format simple inclut ces champs de niveau supérieur.The simple format includes these top-level fields.

ParamètreParameter DescriptionDescription
RecognitionStatus État, tel que Success pour une reconnaissance ayant réussi.Status, such as Success for successful recognition. Voir le tableau suivant.See next table.
DisplayText Le texte reconnu après mise en majuscules, ponctuation, normalisation du texte inversée (conversion de texte lu en formes plus courtes, par exemple 200 pour « deux cents » ou « Dr. Smith » pour « docteur smith ») et masquage des grossièretés.The recognized text after capitalization, punctuation, inverse text normalization (conversion of spoken text to shorter forms, such as 200 for "two hundred" or "Dr. Smith" for "doctor smith"), and profanity masking. Présent uniquement en cas de réussite.Present only on success.
Offset Moment (en unités de 100 nanosecondes) à partir duquel la voix identifiée commence dans le flux audio.The time (in 100-nanosecond units) at which the recognized speech begins in the audio stream.
Duration Durée (en unités de 100 nanosecondes) de la voix reconnue dans le flux audio.The duration (in 100-nanosecond units) of the recognized speech in the audio stream.

Le champ RecognitionStatus peut contenir ces valeurs :The RecognitionStatus field may contain these values:

StatutStatus DescriptionDescription
Success La reconnaissance a réussi et le champ DisplayText est présent.The recognition was successful and the DisplayText field is present.
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.Speech was detected in the audio stream, but no words from the target language were matched. Signifie généralement que la langue de reconnaissance est différente de celle parlée par l’orateur.Usually means the recognition language is a different language from the one the user is speaking.
InitialSilenceTimeout Le début du flux audio contenait uniquement un silence, et le service a dépassé son délai d’attente de paroles.The start of the audio stream contained only silence, and the service timed out waiting for speech.
BabbleTimeout Le début du flux audio contenait uniquement du bruit, et le service a dépassé son délai d’attente de paroles.The start of the audio stream contained only noise, and the service timed out waiting for speech.
Error Le service de reconnaissance a rencontré une erreur interne et n’a pas pu continuer.The recognition service encountered an internal error and could not continue. Réessayez si possible.Try again if possible.

Nota

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.If the audio consists only of profanity, and the profanity query parameter is set to remove, the service does not return a speech result.

Le format detailed comprend des formes supplémentaires de résultats reconnus.The detailed format includes additional forms of recognized results. Lorsque vous utilisez le format detailed, DisplayText est fourni en tant que Display pour chaque résultat dans la liste NBest.When using the detailed format, DisplayText is provided as Display for each result in the NBest list.

L’objet dans la liste NBest peut inclure :The object in the NBest list can include:

ParamètreParameter DescriptionDescription
Confidence Le score de confiance de l’entrée, compris entre 0,0 (aucun niveau de confiance) et 1,0 (confiance totale)The confidence score of the entry from 0.0 (no confidence) to 1.0 (full confidence)
Lexical La forme lexicale du texte reconnu : les mots reconnus.The lexical form of the recognized text: the actual words recognized.
ITN La forme « normalisation du texte inversée » (canonique) du texte reconnu, avec numéros de téléphone, chiffres, abréviations (« docteur smith » en « dr smith ») et autres transformations appliquées.The inverse-text-normalized ("canonical") form of the recognized text, with phone numbers, numbers, abbreviations ("doctor smith" to "dr smith"), and other transformations applied.
MaskedITN La forme « normalisation du texte inversée » avec masquage des grossièretés appliqué, si nécessaire.The ITN form with profanity masking applied, if requested.
Display La forme d’affichage du texte reconnu, avec signes de ponctuation et mise en majuscules ajoutés.The display form of the recognized text, with punctuation and capitalization added. Ce paramètre est identique à la valeur DisplayText fournie lorsque le format est défini sur simple.This parameter is the same as DisplayText provided when format is set to simple.
AccuracyScore Précision de prononciation du discours.Pronunciation accuracy of the speech. La précision indique dans quelle mesure les phonèmes correspondent à la prononciation d’un intervenant de langue maternelle.Accuracy indicates how closely the phonemes match a native speaker's pronunciation. Le score de précision au niveau du mot et du texte intégral est agrégé à partir du score de précision du niveau du phonème.Word and full text level accuracy score is aggregated from phoneme level accuracy score.
FluencyScore Fluidité du discours concerné.Fluency of the given speech. La fluidité indique dans quelle mesure le discours correspond à l’utilisation qu’un orateur de langue maternelle fait des pauses entre les mots.Fluency indicates how closely the speech matches a native speaker's use of silent breaks between words.
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.Completeness of the speech, determined by calculating the ratio of pronounced words to reference text input.
PronScore Score global indiquant la qualité de prononciation du discours concerné.Overall score indicating the pronunciation quality of the given speech. Il est agrégé à partir de AccuracyScore, FluencyScore et CompletenessScore avec une pondération.This is aggregated from AccuracyScore, FluencyScore and CompletenessScore with weight.
ErrorType Cette valeur indique si un mot est omis, inséré ou mal prononcé par rapport à ReferenceText.This value indicates whether a word is omitted, inserted or badly pronounced, compared to ReferenceText. Les valeurs possibles sont None (aucune erreur sur ce mot), Omission, Insertion et Mispronunciation.Possible values are None (meaning no error on this word), Omission, Insertion and Mispronunciation.

Exemples de réponsesSample responses

Réponse classique pour la reconnaissance simple :A typical response for simple recognition:

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

Réponse classique pour la reconnaissance detailed :A typical response for detailed recognition:

{
  "RecognitionStatus": "Success",
  "Offset": "1236645672289",
  "Duration": "1236645672289",
  "NBest": [
      {
        "Confidence" : "0.87",
        "Lexical" : "remind me to buy five pencils",
        "ITN" : "remind me to buy 5 pencils",
        "MaskedITN" : "remind me to buy 5 pencils",
        "Display" : "Remind me to buy 5 pencils.",
      }
  ]
}

Réponse classique pour la reconnaissance avec évaluation de la prononciation :A typical response for recognition with pronunciation assessment:

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

Étapes suivantesNext steps