Real-time speech recognition API reference - Intelligent Speech Interaction

Facturation et limites de simultanéité

La reconnaissance vocale en temps réel est disponible en version d'essai et en version commerciale. Pour plus de détails sur la facturation, consultez la section Éléments facturables.

Remarques sur l'utilisation

Avant d'appeler l'API, assurez-vous que le format audio, la fréquence d'échantillonnage et le modèle de projet répondent aux exigences suivantes.

Entrées prises en charge : audio mono avec une profondeur de bits de 16 bits au format PCM, WAV encodé en PCM ou Ogg Opus.
Fréquences d'échantillonnage prises en charge : 8 000 Hz et 16 000 Hz.
Les fonctionnalités de sortie configurables incluent les résultats de reconnaissance intermédiaires, l'ajout de ponctuation lors du post-traitement et la conversion des chiffres chinois en chiffres arabes.

La diarisation des locuteurs et l'analyse des rôles des locuteurs ne sont pas prises en charge.
Le modèle de projet détermine la langue ou le dialecte de reconnaissance. Il ne peut pas être spécifié dans un paramètre de requête. Pour obtenir des instructions sur la configuration du modèle, consultez la section Gérer les projets.

Endpoints

Type d'accès

Description

URL

Accès Internet

Utilisez l'endpoint de la région Singapour.

wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1

Flux d'interaction

Remarque

Le champ header.task_id dans une réponse du serveur identifie la tâche de reconnaissance. Enregistrez cette valeur pour le dépannage.

1. S'authentifier

Utilisez un jeton NLS pour vous authentifier lors de l'établissement d'une connexion WebSocket au serveur.

Pour obtenir des instructions, consultez Obtenir un jeton à l'aide d'un SDK.

2. Démarrer la reconnaissance

Envoyez une commande StartTranscription avec les paramètres de reconnaissance. Commencez la diffusion audio après que le serveur a renvoyé TranscriptionStarted. Lorsque vous utilisez un SDK, configurez les paramètres via ses méthodes correspondantes. Le tableau suivant décrit les paramètres.

Paramètre	Type	Obligatoire	Description
appkey	String	Oui	L'Appkey d'un projet créé dans la console Intelligent Speech Interaction.
format	String	Non	Le format audio : pcm, wav ou opus.
sample_rate	Integer	Non	La fréquence d'échantillonnage audio. Valeur par défaut : 16 000 Hz. Dans la console, configurez le projet avec un modèle qui prend en charge la fréquence d'échantillonnage audio et le cas d'utilisation.
enable_intermediate_result	Boolean	Non	Indique s'il faut renvoyer les résultats de reconnaissance intermédiaires. Valeur par défaut : false.
enable_punctuation_prediction	Boolean	Non	Indique s'il faut ajouter la ponctuation lors du post-traitement. Valeur par défaut : false.
enable_inverse_text_normalization	Boolean	Non	Indique s'il faut activer la normalisation inverse du texte (ITN) pour convertir les chiffres chinois en chiffres arabes. Valeur par défaut : false.
customization_id	String	Non	L'ID du modèle linguistique personnalisé.
vocabulary_id	String	Non	L'ID du vocabulaire de mots-clés personnalisés.
max_sentence_silence	Integer	Non	Le seuil de silence pour la segmentation des phrases, en millisecondes. Après la détection de la parole, un silence plus long que ce seuil met fin à la phrase. Valeurs valides : 200 à 2000. Valeur par défaut : 800. Lorsque enable_semantic_sentence_detection est activé, ce seuil n'est pas utilisé pour la segmentation des phrases basée sur le silence. Sa valeur doit toujours se situer dans la plage autorisée. La durée du silence est calculée à partir des données audio, et non à partir du temps d'attente après l'arrêt de la transmission des données. Pour utiliser la segmentation basée sur le silence, continuez à envoyer de l'audio, y compris les segments silencieux. Dans l'audio PCM, des échantillons de valeur nulle peuvent représenter le silence.
enable_words	Boolean	Non	Indique s'il faut renvoyer les informations sur les mots. Valeur par défaut : false.
disfluency	Boolean	Non	Indique s'il faut supprimer les mots de remplissage. Valeur par défaut : false (désactivé).
speech_noise_threshold	Float	Non	Le seuil de bruit. Valeurs valides : [-1, 1]. La valeur affecte la classification comme suit : Plus la valeur est proche de -1, plus il est probable que le bruit soit classé comme parole. Plus la valeur est proche de +1, plus il est probable que la parole soit classée comme bruit. Important Il s'agit d'un paramètre avancé. Ajustez-le avec prudence et testez l'effet de manière approfondie.
enable_semantic_sentence_detection	Boolean	Non	Indique s'il faut activer la segmentation sémantique des phrases. Valeur par défaut : false. Lors de l'activation de cette fonctionnalité, activez également les résultats intermédiaires en définissant enable_intermediate_result sur true.

3. Recevoir les résultats de reconnaissance

Continuez à diffuser l'audio et à recevoir les événements de reconnaissance. Les extraits JSON suivants illustrent les structures des messages d'événement.

Champs dans l'objet header :

Paramètre

Type

Description

namespace

String

L'espace de noms du message.

name

String

Le nom de l'événement.

status

Integer

Le code d'état, qui indique si la requête a réussi. Consultez la section Codes d'état.

status_text

String

Le message d'état.

task_id

String

L'ID de tâche globalement unique. Enregistrez cette valeur pour le dépannage.

message_id

String

L'ID du message.

SentenceBegin

Un événement SentenceBegin indique que le serveur a détecté le début d'une phrase. Le service détecte automatiquement les limites des phrases. Exemple :

{
        "header": {
                "namespace": "SpeechTranscriber",
                "name": "SentenceBegin",
                "status": 20000000,
                "message_id": "a426f3d4618447519c9d85d1a0d1****",
                "task_id": "5ec521b5aa104e3abccf3d361822****",
                "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
                "index": 1,
                "time": 0
        }
}

Champs dans l'objet payload :

Paramètre

Type

Description

index

Integer

L'index de la phrase, qui commence à 1 et s'incrémente pour chaque phrase.

time

Integer

La durée de l'audio traité jusqu'à présent, en millisecondes.

TranscriptionResultChanged

Un événement TranscriptionResultChanged contient un résultat intermédiaire mis à jour pour la phrase en cours. Ces événements sont renvoyés uniquement lorsque enable_intermediate_result est défini sur true. Exemple :

{
        "header": {
                "namespace": "SpeechTranscriber",
                "name": "TranscriptionResultChanged",
                "status": 20000000,
                "message_id": "dc21193fada84380a3b6137875ab****",
                "task_id": "5ec521b5aa104e3abccf3d361822****",
                "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
                "index": 1,
                "time": 1835,
                "result": "The weather in",
                "confidence": 1.0,
                "words": [{
                        "text": "The",
                        "startTime": 630,
                        "endTime": 930
                }, {
                        "text": "weather",
                        "startTime": 930,
                        "endTime": 1110
                }, {
                        "text": "in",
                        "startTime": 1110,
                        "endTime": 1140
                }]
        }
}

Pour cet événement, header.name est TranscriptionResultChanged, indiquant un résultat de reconnaissance intermédiaire.

Champs dans l'objet payload :

Paramètre

Type

Description

index

Integer

L'index de la phrase, qui commence à 1 et s'incrémente pour chaque phrase.

time

Integer

La durée de l'audio traité jusqu'à présent, en millisecondes.

result

String

Le résultat de reconnaissance pour la phrase en cours.

words

List< Word >

Informations sur les mots pour la phrase en cours. Nécessite que enable_words soit défini sur true.

confidence

Double

Le score de confiance pour le résultat de reconnaissance, dans la plage [0,0, 1,0]. Une valeur plus élevée indique une confiance plus grande.

SentenceEnd

Un événement SentenceEnd indique que le serveur a détecté la fin d'une phrase et renvoie le résultat de reconnaissance pour cette phrase. Exemple :

{
        "header": {
                "namespace": "SpeechTranscriber",
                "name": "SentenceEnd",
                "status": 20000000,
                "message_id": "c3a9ae4b231649d5ae05d4af36fd****",
                "task_id": "5ec521b5aa104e3abccf3d361822****",
                "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
                "index": 1,
                "time": 1820,
                "begin_time": 0,
                "result": "The weather in Beijing.",
                "confidence": 1.0,
                "words": [{
                        "text": "The",
                        "startTime": 630,
                        "endTime": 930
                }, {
                        "text": "weather",
                        "startTime": 930,
                        "endTime": 1110
                }, {
                        "text": "in Beijing",
                        "startTime": 1110,
                        "endTime": 1380
                }]
        }
}

Pour cet événement, header.name est SentenceEnd, indiquant la fin d'une phrase.

Champs dans l'objet payload :

Paramètre

Type

Description

index

Integer

L'index de la phrase, qui commence à 1 et s'incrémente pour chaque phrase.

time

Integer

La durée de l'audio traité jusqu'à présent, en millisecondes.

begin_time

Integer

L'heure de l'événement SentenceBegin correspondant, en millisecondes.

result

String

Le résultat de reconnaissance.

words

List< Word >

Informations sur les mots pour la phrase en cours. Nécessite que enable_words soit défini sur true.

confidence

Double

Le score de confiance pour le résultat de reconnaissance, dans la plage [0,0, 1,0]. Une valeur plus élevée indique une confiance plus grande.

Champs dans chaque entrée words :

Paramètre

Type

Description

text

String

Le texte du mot.

startTime

Integer

L'heure de début du mot, en millisecondes.

endTime

Integer

L'heure de fin du mot, en millisecondes.

4. Terminer la reconnaissance

Après avoir envoyé tout l'audio, envoyez StopTranscription pour terminer la tâche de reconnaissance. Le serveur traite l'audio restant et renvoie TranscriptionCompleted lorsque la tâche est terminée. Fermez la connexion uniquement après avoir reçu cet événement.

StopTranscription ne force pas une limite de phrase tout en maintenant la tâche en cours d'exécution. Si l'audio restant contient de la parole valide, le serveur peut renvoyer SentenceEnd avant de terminer la tâche. Une tâche contenant uniquement du silence ne renvoie pas nécessairement SentenceEnd.

Codes d'état

Utilisez les champs header.status et header.status_text présents dans la réponse pour vérifier l'état de la requête. Les tableaux ci-dessous répertorient les erreurs courantes et leurs solutions.

Codes d'erreur courants

Code d'état	Message d'état	Cause	Solution
40000000	Code d'erreur client par défaut. Plusieurs messages d'erreur peuvent utiliser ce code.	Paramètres invalides ou logique de requête incorrecte.	Comparez la requête avec l'exemple de code fourni dans la documentation et testez la requête corrigée.
40000001	Le jeton « xxx » a expiré ; Le jeton « xxx » n'est pas valide	Erreur client générale, généralement causée par un jeton expiré ou non valide.	Comparez la requête avec l'exemple de code fourni dans la documentation et testez la requête corrigée.
40000002	Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'!	Message invalide ou mal formé.	Comparez la requête avec l'exemple de code fourni dans la documentation et testez la requête corrigée.
40000003	PARAMETER_INVALID; Failed to decode url params	Paramètres de requête invalides. Cette erreur survient fréquemment lors des requêtes RESTful.	Comparez la requête avec l'exemple de code fourni dans la documentation et testez la requête corrigée.
40000005	Gateway:TOO_MANY_REQUESTS:Too many requests!	Trop de requêtes simultanées.	Réduisez le nombre de requêtes de reconnaissance simultanées afin de rester dans les limites du quota de concurrence disponible.
40000009	Invalid wav header!	En-tête invalide.	Si vous envoyez un fichier WAV avec le paramètre `format` défini sur `wav`, vérifiez que l'en-tête WAV est valide. Dans le cas contraire, le serveur risque de rejeter le fichier audio.
40000009	Too large wav header!	En-tête WAV invalide dans le flux audio transmis.	Utilisez un format tel que PCM ou Opus. Pour les fichiers audio WAV, assurez-vous que l'en-tête contient la longueur correcte des données.
40000010	Gateway:FREE_TRIAL_EXPIRED:The free trial has expired!	La période d'essai a expiré et l'édition commerciale n'est pas activée, ou le compte présente des impayés.	Vérifiez l'activation du service et le solde du compte.
40010001	Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal	API ou paramètre non pris en charge.	Vérifiez les paramètres de la requête par rapport à la documentation de l'API et corrigez-les en fonction du message d'erreur. Par exemple, vérifiez l'URL lorsque vous effectuez une requête RESTful avec curl.
40010003	Gateway:DIRECTIVE_INVALID:[xxx]	Erreur client générale.	Le client a envoyé un paramètre ou une commande invalide. Utilisez les détails d'erreur spécifiques à l'API et la documentation pour corriger la requête.
40010004	Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!	Le client a fermé la connexion avant la fin de la requête.	Fermez la connexion après avoir reçu l'événement TranscriptionCompleted.
40010005	Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping!	Le client a envoyé une commande non prise en charge dans l'état actuel.	Vérifiez la séquence des commandes. N'envoyez pas à nouveau StopTranscription pendant l'arrêt de la tâche.
40020105	Meta:APPKEY_NOT_EXIST:Appkey not exist!	L'Appkey spécifié n'existe pas.	Vérifiez l'Appkey dans la configuration du projet sur la console.
40020106	Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch!	L'Appkey et le jeton appartiennent à des UID de compte différents.	Assurez-vous que l'Appkey et le jeton appartiennent au même compte. N'utilisez pas l'Appkey d'un compte avec un jeton provenant d'un autre compte.
403	Forbidden	Le jeton n'est pas valide, par exemple parce qu'il n'existe pas ou a expiré.	Spécifiez un jeton valide. Obtenez un nouveau jeton avant l'expiration du jeton actuel.
41000003	MetaInfo doesn't have end point info	Les informations de routage n'ont pas pu être obtenues pour l'Appkey.	Assurez-vous que l'Appkey et le jeton appartiennent au même compte. N'utilisez pas l'Appkey d'un compte avec un jeton provenant d'un autre compte.
41010101	UNSUPPORTED_SAMPLE_RATE	Fréquence d'échantillonnage non prise en charge.	La reconnaissance vocale en temps réel prend en charge les fréquences d'échantillonnage de 8 000 Hz et 16 000 Hz.
41040201	Realtime:GET_CLIENT_DATA_TIMEOUT:Client data does not send continuously!	Le délai d'attente du serveur a été atteint en attendant les données du client.	Envoyez l'audio en continu à un débit temps réel. Une fois tout l'audio envoyé, envoyez StopTranscription et attendez TranscriptionCompleted avant de fermer la connexion.
50000000	GRPC_ERROR:Grpc error!	Erreur intermittente causée par des facteurs tels que la charge du serveur ou les conditions réseau.	Réessayez la requête.
50000001	GRPC_ERROR:Grpc error!	Erreur intermittente causée par des facteurs tels que la charge du serveur ou les conditions réseau.	Réessayez la requête.
52010001	GRPC_ERROR:Grpc error!	Erreur intermittente causée par des facteurs tels que la charge du serveur ou les conditions réseau.	Réessayez la requête.

Codes d'erreur de la reconnaissance vocale en temps réel

Code d'état

Message d'état

Cause

Solution

40000004

Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time

Le client n'a envoyé aucune donnée pendant plus de 10 secondes après l'établissement de la connexion.

Après l'établissement de la connexion, diffusez l'audio en continu au fur et à mesure de sa capture. Une fois tout l'audio envoyé, envoyez StopTranscription et attendez TranscriptionCompleted avant de fermer la connexion.

40270002

NO_VALID_AUDIO_ERROR

Audio invalide.

Aucun texte valide n'a été reconnu à partir de l'audio.

40270003

DECODE_ERROR

Échec du décodage de l'audio.

Définissez le paramètre format pour qu'il corresponde au format audio réel.

41000002

APPKEY_KEY_IS_NULL

Le paramètre appkey n'est pas correctement défini.

Reportez-vous à la documentation de l'API et aux exemples de code.