Skip to main content

Fun-ASR 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 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.

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
Lorsque vous soumettez une tâche via le nouveau domaine (https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com), le corps de la requête doit impérativement contenir l'objet parameters. Même si aucun paramètre n'est nécessaire, transmettez un objet vide {}. À défaut, la tâche sera bien soumise, mais la reconnaissance échouera.

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.

Corps de la requête

  • Appel de base
  • Mots-clés intégrés
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": "fun-asr",
        "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.
parametersobject(Facultatif)Objet contenant les paramètres de la requête.
Lorsque vous utilisez le nouveau domaine (https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com), le champ parameters est obligatoire. Même si aucun paramètre n'est nécessaire, transmettez un objet vide {}. Si vous omettez ce champ, la tâche sera bien soumise, mais l'interface de requête de tâche signalera un échec de reconnaissance.

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.
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’à 1 valeur. Au-delà, seules les 1 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.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.