Cette rubrique détaille les paramètres et le fonctionnement de l'API HTTP dédiée à la reconnaissance vocale en différé avec Qwen-Audio-ASR-Filetrans.
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.
Si un déploiement dédié renvoie
current user api does not support asynchronous calls, définissez X-DashScope-Async sur disable et utilisez une requête synchrone.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://.contextarray(object)(Facultatif)Liste de messages fournissant un contexte de conversation optionnel pour améliorer la précision de la reconnaissance.
Propriétés role string(Obligatoire)Rôle du message. Valeurs valides :
array(object)(Obligatoire)Liste des éléments constituant le contenu du message.
Propriétés type string(Obligatoire)Type de contenu. Valeurs valides :
string(Conditionnellement obligatoire)Si type vaut input_text, saisissez les résultats de reconnaissance de la parole utilisateur des tours précédents ou une liste de mots spécifiques au domaine. Si type vaut text, saisissez les réponses du grand modèle linguistique des tours précédents. Le texte est compté caractère par caractère (chaque caractère compte pour 1). La longueur cumulée des champs text pour l'ensemble des messages d'un tour de conversation ne doit pas dépasser 400 caractères. Tout excédent est tronqué par la fin. | |
parametersobject(Obligatoire)Incluez toujours parameters. Si aucune option n’est nécessaire, transmettez un objet vide {}. L’omission de ce champ entraîne l’échec de la tâche de transcription soumise.
Propriétés keep_dialect boolean (Facultatif)Pris en charge uniquement par qwen-audio-3.1-asr-flash-filetrans. La valeur par défaut, false, transcrit les dialectes en mandarin standard. Définissez la valeur sur true pour conserver les expressions dialectales.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.Transmis sous forme de paires clé-valeur, où la clé correspond au texte du mot-clé (string) et la valeur à son poids (integer). Aucune liste de mots-clés ne doit être créée au préalable. Le poids s'étend de [1, 5] ou peut être fixé à 50 : une valeur comprise dans [1, 5] augmente la probabilité que le modèle génère ce mot à mesure qu'elle croît ; une valeur de 50 désigne un super mot-clé, ce qui améliore considérablement le rappel, mais le nombre de super mots-clés ne peut excéder 50.Adapté à une optimisation temporaire des mots-clés au niveau de la session.Lorsque les mots-clés instantanés et précompilés sont configurés ensemble, les deux listes sont fusionnées. Si la liste fusionnée dépasse 2000 mots-clés, 2000 sont sélectionnés au hasard. Pour plus de détails sur l'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’à 4 valeurs. Au-delà, seules les 4 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. La description de facturation ci-dessous s’applique à qwen-audio-3.0-asr-flash-filetrans. qwen-audio-3.1-asr-flash-filetrans est facturé selon l’utilisation des tokens. |
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. |