Paramètres et détails de l'API HTTP pour la reconnaissance vocale non temps réel Paraformer.
Prérequis
Vous avez activé le service et obtenu une clé API. Configurez la clé API comme variable d'environnement plutôt que de la coder en dur dans votre code afin d'éviter les risques de sécurité liés à une fuite de code.
Interface de soumission de tâche
Informations de base
| Description de l'endpoint API | Soumet une tâche de reconnaissance vocale. |
| URL | |
| Méthode de requête | POST |
| En-têtes de requête | |
| Corps du message | Le code suivant présente un corps de message contenant tous les paramètres de requête. Vous pouvez omettre les champs facultatifs selon vos besoins. |
Paramètres de requête
Cliquez pour afficher un exemple de requête
Cliquez pour afficher un exemple de requête
| Paramètre | Type | Valeur par défaut | Obligatoire | Description |
|---|---|---|---|---|
| model | string | Oui | Nom du modèle Paraformer utilisé pour la transcription de fichiers audio et vidéo. Pour plus d'informations, consultez la section modèles. | |
| file_urls | array[string] | Oui | Liste des URL pour la transcription de fichiers audio et vidéo (HTTP/HTTPS). Une seule requête prend en charge 1 URL unique.Si vos fichiers audio sont stockés dans OSS, l'API RESTful prend en charge les URL temporaires commençant par le préfixe oss://. | |
| vocabulary_id | string | Non | ID du vocabulaire personnalisé. Pris en charge par les modèles v2+ avec configurations linguistiques. Les mots-clés associés à cet ID s'appliquent à la reconnaissance vocale en cours. Désactivé par défaut. Pour l'utilisation, consultez Mots-clés personnalisés. | |
| channel_id | array[integer] | [0] | Non | Spécifie les index des pistes audio à reconnaître dans un fichier audio multipiste. Les index commencent à 0. Par exemple, [0] correspond à la reconnaissance de la première piste, tandis que [0, 1] correspond à la reconnaissance simultanée des deux premières pistes. Si ce paramètre est omis, seule la première piste est traitée par défaut. |
| disfluency_removal_enabled | boolean | false | Non | Filtre les mots de remplissage. Désactivé par défaut. |
| timestamp_alignment_enabled | boolean | false | Non | Active la fonctionnalité d'alignement temporel. Désactivée par défaut. |
| special_word_filter | string | Non | Définit les mots sensibles à traiter lors de la reconnaissance vocale et permet d'appliquer différentes méthodes de traitement selon les mots concernés.En l'absence de ce paramètre, le système applique sa logique de filtrage intégrée : les mots figurant dans la liste des mots sensibles d'Alibaba Cloud Model Studio sont remplacés par des astérisques (*) de même longueur dans les résultats.Si ce paramètre est renseigné, les stratégies suivantes sont disponibles :
| |
| language_hints | array[string] | ["zh", "en"] | Non | Indique les codes de langue de la parole à reconnaître.Ce paramètre concerne exclusivement le modèle paraformer-v2.Codes de langue pris en charge :
|
| diarization_enabled | boolean | false | Non | Diarisation automatique des locuteurs. Cette option est désactivée par défaut.Elle s'applique uniquement aux flux audio mono ; les pistes multicanaux ne sont pas compatibles.Une fois activée, les résultats incluent un champ speaker_id permettant de différencier les intervenants.Si vous activez cette fonctionnalité, veillez à ce que la durée de l'enregistrement n'excède pas 2 heures, sous peine d'échec ou de délai d'attente dépassé. speaker_id, reportez-vous à la section Description des résultats de reconnaissance. |
| speaker_count | integer | Non | Valeur indicative du nombre de locuteurs (entier compris entre 2 et 100 inclus).Ce paramètre n'est pris en compte que si diarization_enabled vaut true.Par défaut, le système détermine automatiquement ce nombre. Définir cette valeur aide l'algorithme à cibler le nombre indiqué, sans toutefois garantir un résultat exact. |
Paramètres de réponse
Cliquez pour afficher un exemple de réponse
Cliquez pour afficher un exemple de réponse
Paramètre | Type | Description |
task_status | string | L'état de la tâche. |
task_id | string | L'ID de la tâche. Cet ID est transmis en tant que paramètre de requête dans l'interface d'interrogation de tâche. |
Interface d'interrogation de tâche
Informations de base
| Description de l'endpoint API | Interroge l'état et le résultat d'une tâche de reconnaissance vocale. |
| URL | |
| Méthode de requête | GET |
| En-têtes de requête | |
| Corps du message | Aucun. |
Paramètres de requête
Cliquez pour afficher un exemple de requête
Cliquez pour afficher un exemple de requête
Paramètre | Type | Valeur par défaut | Obligatoire | Description |
|---|---|---|---|---|
task_id | string | - | Oui | ID de tâche requis pour l'interrogation. Renvoyé par l'interface de soumission de tâche. |
Paramètres de réponse
Cliquez pour afficher un exemple de réponse
Cliquez pour afficher un exemple de réponse
SUCCEEDED dès qu'une seule sous-tâche réussit. Il est donc nécessaire de vérifier le champ subtask_status pour connaître le résultat individuel de chaque sous-tâche.- Exemple normal
- Exemple d'exception
Paramètre | Type | Description |
|---|---|---|
task_id | string | Identifiant de la tâche interrogée. |
task_status | string | État actuel de la tâche interrogée. Pour les tâches comportant plusieurs sous-tâches, task_status affiche |
subtask_status | string | État de la sous-tâche. |
file_url | string | URL du fichier traité dans le cadre de la transcription. |
transcription_url | string | Lien permettant de récupérer le résultat de reconnaissance (valable 24 heures). Passé ce délai, l'interrogation de la tâche et le téléchargement des résultats échoueront. Le résultat est enregistré au format JSON. Vous pouvez le télécharger via ce lien ou le lire directement par une requête HTTP. Pour plus de détails sur les champs JSON, consultez la section Description des résultats de reconnaissance. |
Description des résultats de reconnaissance
Le résultat de la reconnaissance est enregistré dans un fichier JSON.
Cliquez pour afficher un exemple de résultat de reconnaissance
Cliquez pour afficher un exemple de résultat de reconnaissance
Paramètre | Type | Description |
|---|---|---|
audio_format | string | Format audio du fichier source. |
channels | array[integer] | Index des pistes audio du fichier source. Renvoie [0] pour un audio mono, [0, 1] pour un audio à deux pistes, etc. |
original_sampling_rate | integer | Fréquence d'échantillonnage (Hz) de l'audio dans le fichier source. |
original_duration | integer | Durée originale de l'audio (ms) du fichier source. |
channel_id | integer | Index de la piste audio du résultat de transcription, commençant à 0. |
content_duration | integer | Durée (ms) du contenu identifié comme parole dans la piste audio. Le service de reconnaissance vocale Paraformer ne transcrit et ne mesure que le contenu identifié comme parole dans la piste audio, et facture en conséquence. Le contenu non vocal n'est ni mesuré ni facturé. Généralement, la durée du contenu vocal est inférieure à la durée audio originale. Étant donné que la détermination de la présence de contenu vocal est effectuée par un modèle d'IA, il peut y avoir un léger écart avec la réalité. |
transcript | string | Résultat de transcription vocale au niveau du paragraphe. |
sentences | array | Résultat de transcription vocale au niveau de la phrase. |
words | array | Résultat de transcription vocale au niveau du mot. |
begin_time | integer | Horodatage de début (ms). |
end_time | integer | Horodatage de fin (ms). |
text | string | Résultat de la transcription vocale. |
speaker_id | integer | Index du locuteur actuel, commençant à 0, utilisé pour distinguer les différents locuteurs. Ce champ ne s'affiche dans les résultats de reconnaissance que lorsque la diarisation des locuteurs est activée. |
punctuation | string | Ponctuation prédite après le mot (le cas échéant). |
Exemple complet
Utilisez les bibliothèques HTTP intégrées pour mettre en œuvre les requêtes de soumission et d'interrogation de tâches. Soumettez d'abord la tâche de reconnaissance, puis effectuez des interrogations répétées jusqu'à son achèvement.
Le code suivant fournit un exemple en Python :
Codes d'erreur
Si vous rencontrez des erreurs, consultez la section Codes d'erreur pour le dépannage.
Si le problème persiste, rejoignez la communauté des développeurs pour signaler le problème et fournir l'ID de requête pour une investigation plus approfondie.
Lorsqu'une tâche contient plusieurs sous-tâches, tant qu'une sous-tâche réussit, l'état global de la tâche est marqué comme SUCCEEDED. Vous devez vérifier le champ subtask_status pour déterminer le résultat de chaque sous-tâche.
Exemple de réponse d'erreur :
Plus d'exemples
Pour plus d'exemples, consultez notre référentiel GitHub.
FAQ
Fonctionnalités
Q : Le service prend-il en charge l'audio encodé en Base64 ?
Non. L'audio encodé en Base64 n'est pas pris en charge. Seul l'audio accessible via des URL publiques est accepté. Les flux binaires et la reconnaissance directe de fichiers locaux ne sont pas pris en charge.
Q : Comment fournir des fichiers audio sous forme d'URL accessibles publiquement ?
En général, suivez ces étapes (il s'agit d'une approche générale ; les spécificités varient selon le produit de stockage. Nous recommandons de télécharger l'audio sur Alibaba Cloud OSS) :
1. Choisir une méthode de stockage et d'hébergement
1. Choisir une méthode de stockage et d'hébergement
-
Object Storage Service (recommandé) :
- Utilisez le service de stockage objet d'un fournisseur cloud (tel que Alibaba Cloud OSS) pour télécharger des fichiers audio dans un bucket et les configurer en accès public.
- Avantages : Haute disponibilité, prise en charge de l'accélération CDN, gestion simplifiée.
-
Serveur Web :
- Placez les fichiers audio sur un serveur web prenant en charge l'accès HTTP/HTTPS (comme Nginx ou Apache).
- Avantages : Adapté aux petits projets ou aux tests locaux.
-
Réseau de diffusion de contenu (CDN) :
- Hébergez les fichiers audio sur un CDN et accédez-y via l'URL fournie par le CDN.
- Avantages : Diffusion accélérée des fichiers, adapté aux scénarios à forte concurrence.
2. Télécharger les fichiers audio
2. Télécharger les fichiers audio
-
Object Storage Service :
- Connectez-vous à la console du fournisseur cloud et créez un bucket.
- Téléchargez les fichiers audio et définissez les permissions de fichier sur « lecture publique » ou générez des liens d'accès temporaires.
-
Serveur Web :
- Placez les fichiers audio dans le répertoire désigné du serveur (tel que
/var/www/html/audio/). - Assurez-vous que les fichiers sont accessibles via HTTP/HTTPS.
- Placez les fichiers audio dans le répertoire désigné du serveur (tel que
3. Générer une URL accessible publiquement
3. Générer une URL accessible publiquement
-
Object Storage Service :
- Après le téléchargement, le système génère automatiquement une URL d'accès public (généralement au format
https://<bucket-name>.<region>.aliyuncs.com/<file-name>). - Si vous avez besoin d'un domaine plus convivial, vous pouvez lier un domaine personnalisé et activer HTTPS.
- Après le téléchargement, le système génère automatiquement une URL d'accès public (généralement au format
-
Serveur Web :
- L'URL d'accès au fichier correspond généralement à l'adresse du serveur suivie du chemin du fichier (telle que
https://your-domain.com/audio/file.mp3).
- L'URL d'accès au fichier correspond généralement à l'adresse du serveur suivie du chemin du fichier (telle que
-
CDN :
- Après avoir configuré l'accélération CDN, utilisez l'URL fournie par le CDN (telle que
https://cdn.your-domain.com/audio/file.mp3).
- Après avoir configuré l'accélération CDN, utilisez l'URL fournie par le CDN (telle que
4. Vérifier l'accessibilité de l'URL
4. Vérifier l'accessibilité de l'URL
- Ouvrez l'URL dans un navigateur et vérifiez si le fichier audio peut être lu.
- Utilisez des outils (tels que
curlou Postman) pour vérifier si l'URL renvoie une réponse HTTP correcte (code d'état 200).
oss:// ne sont pas prises en charge.
Lors de l'utilisation de l'API RESTful, si les fichiers audio sont stockés dans Alibaba Cloud OSS, les URL temporaires avec le préfixe oss:// sont prises en charge :
- L'URL temporaire est valide pendant 48 heures et ne peut plus être utilisée après expiration. Ne l'utilisez pas dans un environnement de production.
- L'API permettant d'obtenir un identifiant de téléchargement est limitée à 100 QPS et ne prend pas en charge la mise à l'échelle horizontale. Ne l'utilisez pas dans des environnements de production, des scénarios à forte concurrence ou des tests de charge.
- Pour les environnements de production, utilisez un service de stockage stable tel que OSS afin de garantir la disponibilité à long terme des fichiers et d'éviter les problèmes de limitation de débit.
Q : Combien de temps faut-il pour obtenir les résultats de reconnaissance ?
Après soumission, la tâche passe à l'état de file d'attente (PENDING). Le temps d'attente dépend de la longueur de la file et de la durée du fichier ; il ne peut pas être estimé avec précision, mais se termine généralement en quelques minutes. Veuillez patienter. Les fichiers audio plus longs nécessitent plus de temps de traitement.
Dépannage
Si vous rencontrez une erreur, reportez-vous aux informations dans Codes d'erreur.
Q : Que faire si les résultats de reconnaissance ne sont pas synchronisés avec la lecture audio ?
Définissez le paramètre de requête timestamp_alignment_enabled sur true. Cela synchronise les résultats de reconnaissance avec la lecture audio.
Q : Que faire si j'obtiens une erreur InvalidFile.DownloadFailed après avoir soumis une tâche ?
Vérifiez si l'URL du fichier contient des espaces, des caractères chinois ou d'autres caractères spéciaux. Si le nom du fichier comprend des espaces (par exemple, « Enregistrement Réunion T1 2024.mp4 »), encodez le nom du fichier en URL en remplaçant les espaces par %20 avant de le transmettre au paramètre file_urls.
Q : Que faire si l'URL d'accès public temporaire d'un fichier audio OSS est inaccessible ?
Définissez X-DashScope-OssResourceResolve sur enable dans les en-têtes.
Non recommandé.
Le SDK Java et le SDK Python de reconnaissance vocale non temps réel Paraformer ne prennent pas en charge la configuration des en-têtes.
Q : Impossible d'obtenir des résultats après une interrogation continue ?
Cela peut être dû à une limitation de débit. Veuillez patienter. Si vous avez besoin d'une extension de capacité, rejoignez la communauté des développeurs pour en faire la demande.
Q : Pourquoi n'y a-t-il aucun résultat de reconnaissance (impossible de reconnaître la parole) ?
- Vérifiez si l'audio répond aux exigences (format, fréquence d'échantillonnage).
- Si vous utilisez le modèle
paraformer-v2, vérifiez si le paramètrelanguage_hintsest correct. - Si aucune des solutions ci-dessus ne résout le problème, vous pouvez personnaliser des mots-clés pour améliorer la reconnaissance de termes spécifiques.