Cette rubrique détaille les paramètres et le fonctionnement de l'API HTTP dédiée à la reconnaissance vocale en différé avec Fun-ASR.
Pour connaître les prérequis d'entrée (formats audio pris en charge, limites de taille de fichier et de durée), reportez-vous aux Spécifications audio.
Contrairement aux appels synchrones DashScope qui renvoient immédiatement le résultat dans une requête unique, les appels asynchrones sont conçus pour les fichiers audio volumineux ou les tâches longues. Ce mode repose sur un flux en deux étapes (soumission puis interrogation) afin d'éviter les délais d'expiration liés à une attente prolongée :
Soumet une tâche de reconnaissance vocale. Cette interface répond de manière asynchrone ; surveillez donc l'état de la tâche via l'Interface de requête de tâche.
Interroge l'état d'exécution et le résultat d'une tâche de reconnaissance vocale. Interrogez cette interface de manière répétée jusqu'à ce que la tâche atteigne un état terminal.
Pour plus de détails, consultez Gérer les tâches asynchrones : vous pouvez interroger par lot les tâches de reconnaissance vocale en différé soumises au cours des dernières 24 heures, et annuler celles qui se trouvent à l'état
Le résultat de la reconnaissance est enregistré dans un fichier JSON.
Les paramètres suivants méritent une attention particulière :
Fonctionnement
Contrairement aux appels synchrones DashScope qui renvoient immédiatement le résultat dans une requête unique, les appels asynchrones sont conçus pour les fichiers audio volumineux ou les tâches longues. Ce mode repose sur un flux en deux étapes (soumission puis interrogation) afin d'éviter les délais d'expiration liés à une attente prolongée :
-
Étape 1 : Soumettre la tâche.
- Le client envoie une requête de traitement asynchrone.
- Après validation de la requête, le serveur n'exécute pas immédiatement la tâche. Il renvoie plutôt un identifiant unique
task_idconfirmant la création réussie de la tâche.
-
Étape 2 : Récupérer le résultat.
- Le client utilise le
task_idretourné pour interroger régulièrement l'interface de requête. - Une fois la tâche terminée, l'interface de requête renvoie le résultat final de la reconnaissance.
- Le client utilise le
Endpoints du service
- Singapore
- China (Beijing)
Interface de soumission de tâche :
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcriptionInterface de requête de tâche : GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.En-têtes de requête
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
Authorization | string | Oui | Jeton d'authentification au format Bearer <your_api_key>. Remplacez « <your_api_key> » par votre clé API réelle. Requis pour l'interface de soumission de tâche ainsi que pour l'interface de requête de tâche. |
Content-Type | string | Oui | Type MIME du corps de la requête. Uniquement requis pour l'interface de soumission de tâche. Valeur fixe : application/json. |
X-DashScope-Async | string | Oui | Indicateur de tâche asynchrone. Uniquement requis pour l'interface de soumission de tâche. Valeur fixe : enable. Ne l'omettez pas, sous peine de ne pas pouvoir soumettre la tâche. |
Interface de soumission de tâche
Soumet une tâche de reconnaissance vocale. Cette interface répond de manière asynchrone ; surveillez donc l'état de la tâche via l'Interface de requête de tâche.
Corps de la requête |
L'exemple suivant utilise la région Singapore. Remplacez « {WorkspaceId} » par votre véritable ID d'espace de travail. La configuration varie selon la région. Les régions de Singapore et de Beijing utilisent des clés API différentes. |
modelstring(Obligatoire)Le nom du modèle. | |
inputobject(Obligatoire)Objet contenant les paramètres d'entrée.
Propriétés file_urls array[string](Obligatoire)Liste des URL des fichiers audio ou vidéo à transcrire. Les protocoles HTTP et HTTPS sont pris en charge. Une seule URL est acceptée par requête. Pour connaître les prérequis d'entrée (formats audio, limites de taille et de durée), reportez-vous aux Spécifications audio.Si l'enregistrement est stocké dans Alibaba Cloud OSS, l'API RESTful accepte les URL temporaires préfixées par oss://, contrairement au SDK qui ne prend pas en charge les URL temporaires avec le préfixe oss://. | |
parametersobject(Facultatif)Objet contenant les paramètres de la requête.
Propriétés vocabulary_id string(Facultatif)Identifiant d'une liste de mots-clés précompilée.Générez cet identifiant au préalable en appelant l'API de création de liste de mots-clés. Transmettez-le lors de la reconnaissance pour appliquer les mots-clés de la liste.Idéal lorsque le vocabulaire est connu, relativement stable et que vous souhaitez réutiliser la même liste de mots entre plusieurs requêtes.Pour plus de détails sur l'utilisation, consultez Mots-clés précompilés.vocabulary object(Facultatif)Mots-clés instantanés. Transmettez des paires clé-valeur dont les clés sont les mots-clés (string) et les valeurs sont des poids entiers (integer). Aucune liste précompilée n’est nécessaire.Pour leur utilisation, consultez Mots-clés instantanés.channel_id array[integer](Facultatif)Index des pistes audio à reconnaître dans un fichier multipiste. L'index commence à 0. Par exemple, [0] reconnaît la première piste, tandis que [0, 1] traite simultanément les deux premières pistes. Si vous omettez ce paramètre, seule la première piste est traitée.Valeur par défaut : [0].special_word_filter string(Facultatif) Configurez les mots à remplacer ou supprimer. Le paramètre est une chaîne JSON contenant les champs suivants :
*.Par exemple, remplacez PROJECT par des astérisques de même longueur et supprimez REPORT avec cette valeur :boolean(Facultatif)Active ou désactive la diarisation des locuteurs. Désactivée par défaut.S'applique uniquement à l'audio mono. L'audio multicanal ne prend pas en charge la diarisation des locuteurs.Une fois activée, le résultat de reconnaissance inclut un champ speaker_id permettant de distinguer les différents interlocuteurs.Lorsque la diarisation des locuteurs est activée, veillez à ce que la durée audio reste inférieure à 2 heures. Autrement, la reconnaissance risque d'échouer ou d'expirer. speaker_id, reportez-vous à la Description du résultat de reconnaissance.Valeur par défaut : false.speaker_count integer(Facultatif)Valeur de référence indiquant le nombre de locuteurs. Elle doit correspondre à un entier compris entre 2 et 100 inclus.Par défaut, le nombre de locuteurs est détecté automatiquement. Si vous définissez cette valeur, elle sert uniquement à orienter l'algorithme pour qu'il tente de restituer le nombre indiqué, sans garantie d'exactitude.Aucune valeur par défaut.language_hints array[string](Facultatif)Codes de langue à reconnaître. Si vous ne pouvez pas déterminer la langue à l'avance, laissez ce champ vide pour que le modèle effectue une détection automatique.Vous pouvez définir jusqu’à 1 valeur. Au-delà, seules les 1 premières sont prises en compte.
Cliquez pour afficher les codes de langue pris en charge
|
Corps de la réponse | |
request_idstringIdentifiant unique de cet appel. | |
outputobjectDonnées renvoyées par l'interface de soumission de tâche.
Propriétés task_id stringIdentifiant de la tâche. Transmettez cet ID en tant que string dans l'Interface de requête de tâche.task_statusstringÉtat de la tâche. Renvoie PENDING en cas de soumission réussie. |
Interface de requête de tâche
Interroge l'état d'exécution et le résultat d'une tâche de reconnaissance vocale. Interrogez cette interface de manière répétée jusqu'à ce que la tâche atteigne un état terminal.
Corps de la requête | L'exemple suivant utilise la région Singapore. Remplacez « {WorkspaceId} » par votre véritable ID d'espace de travail. La configuration varie selon la région. Les régions de Singapore et de Beijing utilisent des clés API différentes. |
task_idstring(Obligatoire)Pour interroger une tâche, spécifiez son identifiant. Cet ID correspond au task_id renvoyé lors de l'appel à l'Interface de soumission de tâche. | |
Corps de la réponse | |
request_idstringIdentifiant unique de cet appel. | |
outputobjectDonnées renvoyées par l'interface de requête de tâche.
Propriétés task_id stringIdentifiant de la tâche interrogée.task_statusstringÉtat de la tâche interrogée.Lorsqu'une tâche comporte plusieurs sous-tâches, l'état global est marqué comme SUCCEEDED dès qu'une seule sous-tâche réussit. Vérifiez le champ subtask_status pour connaître le résultat précis d'une sous-tâche donnée.stringHeure de soumission de la tâche.scheduled_timestringHeure de planification de l'exécution de la tâche.end_timestringHeure de fin de la tâche.resultsarray[object]Liste des résultats des sous-tâches, correspondant chacune à un fichier audio à reconnaître.
Propriétés subtask_status stringÉtat de la sous-tâche.file_urlstringURL du fichier traité par la tâche de transcription.transcription_urlstringLien vers le résultat de la reconnaissance. Ce lien reste valide pendant 24 heures. Passé ce délai, vous ne pourrez plus interroger la tâche ni télécharger le résultat via l'URL obtenue lors d'une requête précédente.Le résultat de la reconnaissance est enregistré dans un fichier JSON. Vous pouvez télécharger ce fichier via le lien ci-dessus ou lire directement son contenu à l'aide d'une requête HTTP. Pour la signification de chaque champ du JSON, consultez la Description du résultat de reconnaissance.codestringCode d'erreur de la sous-tâche ayant échoué.messagestringMessage d'erreur de la sous-tâche ayant échoué.objectStatistiques globales d'exécution de la tâche.
Propriétés TOTAL integerNombre total de sous-tâches.SUCCEEDEDintegerNombre de sous-tâches réussies.FAILEDintegerNombre de sous-tâches ayant échoué. |
Autres interfaces : interrogation groupée de l'état des tâches / annulation d'une tâche
Pour plus de détails, consultez Gérer les tâches asynchrones : vous pouvez interroger par lot les tâches de reconnaissance vocale en différé soumises au cours des dernières 24 heures, et annuler celles qui se trouvent à l'état PENDING (en file d'attente).
Description du résultat de reconnaissance
Le résultat de la reconnaissance est enregistré dans un fichier JSON.
| Paramètre | Type | Description |
|---|---|---|
audio_format | string | Format audio du fichier source. |
channels | array[integer] | Index de piste de l'audio dans le fichier source. Pour un audio monopiste, [0] est renvoyé ; pour un audio bipiste, [0, 1] est renvoyé, et ainsi de suite. |
original_sampling_rate | integer | Fréquence d'échantillonnage (Hz) de l'audio dans le fichier source. |
original_duration_in_milliseconds | integer | Durée originale de l'audio (ms) dans le fichier source. |
channel_id | integer | Index de piste du résultat de transcription, commençant à 0. |
content_duration | integer | Durée (ms) du contenu identifié comme parole dans la piste.Le service de modèle de reconnaissance vocale ne transcrit que le contenu d'une piste identifié comme parole, et la facturation s'appuie sur cette durée. Le contenu non parlé n'est ni mesuré ni facturé. Généralement, la durée du contenu parlé est inférieure à la durée audio originale. Étant donné que la présence de parole est déterminée par un modèle d'IA, le résultat peut différer légèrement de la réalité. |
transcript | string | Résultat de transcription au niveau du paragraphe. |
sentences | array | Résultat de transcription au niveau de la phrase. |
words | array | Résultat de transcription 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. |
speaker_id | integer | Index du locuteur actuel, commençant à 0, servant à distinguer les différents intervenants.Ce champ n'apparaît dans le résultat de reconnaissance que si la diarisation des locuteurs est activée. |
punctuation | string | Ponctuation prédite après le mot, le cas échéant. |