Skip to main content

Qwen-Audio-ASR-Filetrans HTTP API for non-real-time speech recognition

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.

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 :
  1. É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_id confirmant la création réussie de la tâche.
  2. Étape 2 : Récupérer le résultat.
    • Le client utilise le task_id retourné 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.

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.
Alibaba Cloud Model Studio a publié des domaines spécifiques à chaque espace de travail pour les régions China (Beijing) et Singapore. Ces nouveaux domaines dédiés offrent des performances supérieures et une meilleure stabilité pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • China (Beijing) : passez de dashscope.aliyuncs.com à {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore : passez de dashscope-intl.aliyuncs.com à {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

En-têtes de requête

ParamètreTypeObligatoireDescription
AuthorizationstringOuiJeton 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-TypestringOuiType MIME du corps de la requête. Uniquement requis pour l'interface de soumission de tâche. Valeur fixe : application/json.
X-DashScope-AsyncstringOuiIndicateur 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

  • Appel de base
  • Mots-clés intégrés
  • Contexte
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.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
         --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
         --header "Content-Type: application/json" \
         --header "X-DashScope-Async: enable" \
         --data '{
        "model": "qwen-audio-3.0-asr-flash-filetrans",
        "input": {
            "file_urls": [
                "{YOUR_AUDIO_URL}"
            ]
        },
        "parameters": {
            "channel_id": [0]
        }
    }'
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://.
  • Une URL temporaire est valide pendant 48 heures et devient inutilisable après expiration. Ne l'utilisez pas en production.
  • L'interface d'obtention des identifiants de téléchargement est limitée à 100 QPS et ne peut pas monter en charge. Ne l'utilisez ni en production, ni dans des scénarios à forte concurrence ou de test de charge.
  • Pour la production, privilégiez un stockage stable tel qu'Alibaba Cloud OSS afin de garantir la disponibilité à long terme des fichiers et d'éviter les limitations de débit.
  • Si une URL de fichier audio pointant vers une URL publique temporaire OSS est inaccessible, définissez X-DashScope-OssResourceResolve sur enable dans l'en-tête de la requête (non recommandé). Le SDK ne permet pas de configurer les en-têtes de requête.
contextarray(object)(Facultatif)Liste de messages fournissant un contexte de conversation optionnel pour améliorer la précision de la reconnaissance.
Le SDK ne prend pas encore en charge cette fonctionnalité.
L'enrichissement contextuel améliore la reconnaissance des termes spécifiques à un domaine. Pour savoir comment l'utiliser, consultez Enrichissement contextuel.Contraintes : Le nombre de messages contextuels de type input_text et text est limité à 5 chacun. En cas de dépassement, seuls les 5 plus récents sont conservés. La longueur totale du texte par tour de conversation (somme des champs text pour user et assistant) ne doit pas excéder 400 caractères (comptage unitaire par caractère). Tout excédent est tronqué par la fin.
Lorsque vous fournissez un contexte, l'ordre des messages dans messages est important : ils doivent être organisés par tour de conversation. Au sein de chaque tour, le message user (de type input_text) doit précéder le message assistant correspondant (de type text). Un message user contenant input_audio doit impérativement figurer en dernière position du tableau messages.

Propriétés

rolestring(Obligatoire)Rôle du message. Valeurs valides :
  • user : résultats de reconnaissance des tours précédents ou liste de mots spécifiques au domaine.
  • assistant : réponses du grand modèle linguistique lors des tours précédents.
contentarray(object)(Obligatoire)Liste des éléments constituant le contenu du message.

Propriétés

typestring(Obligatoire)Type de contenu. Valeurs valides :
  • input_text (facultatif, contexte) : résultats de reconnaissance de la parole utilisateur des tours précédents, ou liste de mots spécifiques au domaine (rôle user). Vous devez également renseigner le champ text.
  • text (facultatif, contexte) : réponses du grand modèle linguistique des tours précédents (rôle assistant). Vous devez également renseigner le champ text.
textstring(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.
Chaque piste spécifiée est facturée indépendamment. Ainsi, demander [0, 1] pour un seul fichier entraîne deux facturations distinctes.
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 :
  • filter_with_signed.word_list : tableau de chaînes des mots à remplacer par le même nombre de caractères *.
  • filter_with_empty.word_list : tableau de chaînes des mots à supprimer du résultat.
  • system_reserved_filter : booléen, true par défaut, qui active également la liste intégrée. Les règles personnalisées restent actives avec false.
Si le paramètre est omis, les mots correspondant à la liste intégrée de mots sensibles Model Studio sont remplacés par le même nombre de caractères *.Par exemple, remplacez project par des astérisques de même longueur et supprimez report avec cette valeur :
{
  "special_word_filter": "{\"filter_with_signed\":{\"word_list\":[\"project\"]},\"filter_with_empty\":{\"word_list\":[\"report\"]},\"system_reserved_filter\":true}"
}
diarization_enabled 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.
Pour consulter un exemple de speaker_id, reportez-vous à la Description du résultat de reconnaissance.Valeur par défaut : false.speaker_count integer(Facultatif)
Ne prend effet que si la diarisation des locuteurs est activée (diarization_enabled défini sur true).
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.
  • zh : Chinois
  • en : Anglais
  • ja : Japonais
  • ko : Coréen
  • vi : Vietnamien
  • th : Thaï
  • id : Indonésien
  • ms : Malais
  • tl : Filipino
  • hi : Hindi
  • ar : Arabe
  • fr : Français
  • de : Allemand
  • es : Espagnol
  • pt : Portugais
  • ru : Russe
  • it : Italien
  • nl : Néerlandais
  • sv : Suédois
  • da : Danois
  • fi : Finnois
  • no : Norvégien
  • el : Grec
  • pl : Polonais
  • cs : Tchèque
  • hu : Hongrois
  • ro : Roumain
  • bg : Bulgare
  • hr : Croate
  • sk : Slovaque

Corps de la réponse

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}
request_idstringIdentifiant unique de cet appel.
outputobjectDonnées renvoyées par l'interface de soumission de tâche.

Propriétés

task_idstringIdentifiant 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.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
         --header "Authorization: Bearer $DASHSCOPE_API_KEY"
task_idstring(Obligatoire)
Ce paramètre est un paramètre de chemin d'URL. Aucun corps de requête n'est attendu.
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_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
    "task_id": "f86ec806-4d73-485f-a24f-************",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "end_time": "2024-09-12 15:11:40.903",
    "results": [
      {
        "file_url": "{YOUR_AUDIO_URL}",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 1,
      "SUCCEEDED": 1,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}
request_idstringIdentifiant unique de cet appel.
outputobjectDonnées renvoyées par l'interface de requête de tâche.

Propriétés

task_idstringIdentifiant 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.
submit_timestringHeure 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.
subtask_statusstringÉ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.codestring
Renvoyé uniquement en cas d'échec de la sous-tâche.
Code d'erreur de la sous-tâche ayant échoué.messagestring
Renvoyé uniquement en cas d'échec de la sous-tâche.
Message d'erreur de la sous-tâche ayant échoué.
task_metricsobjectStatistiques globales d'exécution de la tâche.
TOTALintegerNombre 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.
{
    "file_url":"{YOUR_AUDIO_URL}",
    "properties":{
        "audio_format":"pcm_s16le",
        "channels":[
            0
        ],
        "original_sampling_rate":16000,
        "original_duration_in_milliseconds":3834
    },
    "transcripts":[
        {
            "channel_id":0,
            "content_duration_in_milliseconds":3720,
            "text":"Hello world, this is Alibaba Speech Lab.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is Alibaba Speech Lab.",
                    "sentence_id":1,
                    "speaker_id":0, //This field is displayed only when automatic speaker diarization is enabled
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // Other content is omitted here
                    ]
                }
            ]
        }
    ]
}
Les paramètres suivants méritent une attention particulière :
ParamètreTypeDescription
audio_formatstringFormat audio du fichier source.
channelsarray[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_rateintegerFréquence d'échantillonnage (Hz) de l'audio dans le fichier source.
original_duration_in_millisecondsintegerDurée originale de l'audio (ms) dans le fichier source.
channel_idintegerIndex de piste du résultat de transcription, commençant à 0.
content_durationintegerDuré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.
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é.
transcriptstringRésultat de transcription au niveau du paragraphe.
sentencesarrayRésultat de transcription au niveau de la phrase.
wordsarrayRésultat de transcription au niveau du mot.
begin_timeintegerHorodatage de début (ms).
end_timeintegerHorodatage de fin (ms).
textstringRésultat de la transcription.
speaker_idintegerIndex 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.
punctuationstringPonctuation prédite après le mot, le cas échéant.