Skip to main content

Asynchronous task management API

Certains modèles Model Studio (comme la génération d'images et de vidéos) utilisent une invocation asynchrone en raison de temps de traitement longs. Le flux de travail typique consiste à créer une tâche pour obtenir un ID, puis à interroger le résultat à l'aide de cet ID. Model Studio fournit des API de tâches polyvalentes pour interroger les résultats individuels, vérifier les statuts de plusieurs tâches par lot et annuler les tâches en file d'attente.

Prérequis

Vous pouvez appeler les API de tâches asynchrones via HTTP. Avant d'appeler les API, obtenez et configurez une clé API, puis définissez la clé API comme variable d'environnement.

Interroger le résultat d'une tâche asynchrone

Description de l'API : Interroge le statut et le résultat d'une tâche en fonction de son task_id. Limite de débit : 20 QPS par compte Alibaba Cloud (inclut tous les utilisateurs RAM).
  • Vous pouvez interroger toutes les tâches sous le compte Alibaba Cloud propriétaire de la clé API actuelle, y compris les tâches soumises avec n'importe quelle clé API sous ce compte. Vous ne pouvez pas interroger les tâches d'autres comptes.
  • Les tâches terminées sont conservées pendant 24 heures (consultez la référence de l'API de tâche spécifique pour la période exacte). Après expiration, le système supprime automatiquement les données de la tâche.

Endpoint de requête

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Paramètres de requête

Transmission du paramètre

Champ

Type

Obligatoire

Description

Exemple

Header

Authorization

String

Oui

Clé API au format Bearer sk-xxx

Bearer sk-xxx

Path

task_id

String

Oui

L'ID de la tâche à interroger.

a8532587-xxxx-xxxx-xxxx-0c46b17950d1

Paramètres de réponse

ChampTypeDescriptionExemple
request_idStringL'ID unique pour cette requête.7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
outputObject
  • Si la tâche réussit, output contient l'objet de résultat généré par le modèle. Le contenu varie selon le type de tâche.
  • Si la tâche échoue ou échoue partiellement, output renvoie les champs code et message qui expliquent la raison de l'échec.
  • Pour les tâches comportant plusieurs sous-tâches, output peut contenir à la fois les résultats des sous-tâches réussies et les messages d'erreur pour celles ayant échoué.
output.task_idStringL'ID de la tâche interrogée.a8532587-xxxx-xxxx-xxxx-0c46b17950d1
output.task_statusStringLe statut de la tâche.
  • Pour les tâches à plusieurs sous-tâches, la tâche réussit si au moins une sous-tâche réussit.
  • Les sous-tâches ayant échoué affichent des erreurs spécifiques dans la sortie.
Statut de la tâche :
  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • UNKNOWN
output.submit_timeStringL'heure de soumission de la tâche.2023-12-20 21:36:31.896
output.scheduled_timeStringL'heure de planification de la tâche (lorsqu'elle a commencé à s'exécuter).2023-12-20 21:36:39.009
output.end_timeStringL'heure de fin de la tâche.2023-12-20 21:36:45.913
output.codeStringLe code d'erreur (renvoyé uniquement lorsque la tâche échoue).
output.messageStringLe message d'erreur (renvoyé uniquement lorsque la tâche échoue).
output.task_metricsObjectMétriques de la tâche, y compris les statistiques de statut des sous-tâches.{"TOTAL": 4, // Nombre total de sous-tâches"SUCCEEDED": 3, // Nombre de sous-tâches réussies"FAILED": 1 // Nombre de sous-tâches ayant échoué}
usageObjectLes informations de facturation pour cette requête (varient selon la tâche)."usage": {"image_count": 1}

Exemple de requête

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/73205176-xxxx-xxxx-xxxx-16bd5d902219' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
Si $DASHSCOPE_API_KEY n'est pas définie comme variable d'environnement, remplacez-la par votre clé API réelle (format : Bearer sk-xxx).

Exemple de réponse

{
    "request_id": "45ac7f13-xxxx-xxxx-xxxx-e03c35068d83",
    "output": {
        "task_id": "73205176-xxxx-xxxx-xxxx-16bd5d902219",
        "task_status": "SUCCEEDED",
        "submit_time": "2023-12-20 21:36:31.896",
        "scheduled_time": "2023-12-20 21:36:39.009",
        "end_time": "2023-12-20 21:36:45.913",
        "results": [
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx1.png"
            },
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx2.png"
            },
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx3.png"
            },
            {
                "code": "DataInspectionFailed",
                "message": "Output data may contain inappropriate content.",
            }
        ],
        "task_metrics": {
            "TOTAL": 4,
            "SUCCEEDED": 3,
            "FAILED": 1
        }
    },
    "usage": {
        "image_count": 3
    }
}

Interroger le statut de plusieurs tâches asynchrones

Description de l'API : Interrogez plusieurs tâches asynchrones en utilisant diverses conditions. Vérifiez le statut de plusieurs tâches en une seule requête. Limite de débit : 20 QPS par compte Alibaba Cloud (inclut tous les utilisateurs RAM).
  • Vous pouvez interroger toutes les tâches du compte Alibaba Cloud propriétaire de la clé API actuelle, y compris les tâches soumises avec n'importe quelle clé API associée à ce compte. Vous ne pouvez pas interroger les tâches d'autres comptes.
  • Une fois la période de rétention expirée, le système supprime la tâche et ses données ne sont plus consultables.

Endpoint de la requête

GET https://dashscope.aliyuncs.com/api/v1/tasks

Paramètres de la requête

Transmission des paramètresChampTypeObligatoireDescriptionExemple
HeaderAuthorizationStringOuiLa clé API, au format Bearer sk-xxx.Bearer sk-xxx
Paramstask_idStringNonL'ID de la tâche à interroger. Spécifiez un task_id pour renvoyer uniquement le statut de cette tâche, ou omettez-le pour interroger plusieurs tâches.a8532587-xxxx-xxxx-xxxx-0c46b17950d1
start_timeStringNonHeure de début de la requête au format YYYYMMDDhhmmss. Par défaut, 24 heures avant end_time (si end_time est spécifié), ou les dernières 24 heures (si aucune heure n'est spécifiée). Plage maximale : 24 heures.20230420193058 représente 19:30:58 le 20 avril 2023.
end_timeStringNonHeure de fin de la requête au format YYYYMMDDhhmmss. Par défaut, 24 heures après start_time (si start_time est spécifié). Plage maximale : 24 heures.
model_nameStringNonLe nom du modèle.wanx-v1
statusStringNonLe statut de la tâche :
  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN
page_noIntegerNonLe numéro de page des résultats à renvoyer. Valeur par défaut : 1.
page_sizeIntegerNonLe nombre d'entrées par page. Valeur par défaut : 10.

Paramètres de réponse

ChampTypeDescriptionExemple
request_idStringL'ID unique de cette requête.7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
dataArrayUne liste des résultats de la requête.
"data": [
    {
        "api_key_id": "235",
        "caller_uid": "1808342417264262",
        "end_time": 1682527200093,
        "gmt_create": 1682514589152,
        "model_name": "paraformer-16k-1",
        "region": "cn-hangzhou",
        "request_id": "32b67b58-xxxx-xxxx-xxxx-230f0aee64d9",
        "start_time": 1682515862179,
        "status": "FAILED",
        "task_id": "cf52b16b-xxxx-xxxx-xxxx-17f9c211440c",
        "user_api_unique_key": "apikey:v1:audio:asr:transcription:paraformer-16k-1"
    }
]
data[].api_key_idStringL'ID de la clé API.
data[].caller_parent_idStringL'ID du compte Alibaba Cloud.
data[].caller_uidStringL'ID du compte Alibaba Cloud.
data[].gmt_createLongL'heure de création de la tâche (millisecondes depuis l'époque Unix).
data[].start_timeLongL'heure de début de la tâche, en millisecondes depuis l'époque Unix.
data[].end_timeLongL'heure de fin de la tâche, en millisecondes depuis l'époque Unix.
data[].regionStringLa région. Exemple : cn-hangzhou
data[].request_idStringL'ID de la requête pour la soumission de la tâche.
data[].statusStringLe statut de la tâche :
  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN
data[].task_idStringL'ID de la tâche.
data[].user_api_unique_keyStringUne clé API unique générée à partir des paramètres d'API du modèle lors de la soumission de la tâche.
data[].model_nameStringLe nom du modèle.
page_noIntegerLe numéro de page actuel."page_no": 1
page_sizeIntegerLe nombre d'entrées par page."page_size": 10
total_pageIntegerLe nombre total de pages."total_page": 4
totalIntegerLe nombre total d'entrées."total": 39
codeStringLe code d'erreur renvoyé en cas d'échec de l'appel."code": "Throttling.RateQuota"
messageStringLe message d'erreur renvoyé en cas d'échec de l'appel."message": "Requests rate limit exceeded, please try again later."

Exemple de requête

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/?start_time=xxx&end_time=xxx&status=xxx' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Exemple de réponse

{
    "total": 2,
    "data": [
        {
            "api_key_id": "15xxxx",
            "caller_parent_id": "xxxxxxxxx",
            "caller_uid": "xxxxxxxxx",
            "gmt_create": 1745568428109,
            "model_name": "wanx2.1-kf2v-plus",
            "region": "cn-beijing",
            "request_id": "1abfc3c8-dd25-98da-ad0b-xxxxxx",
            "start_time": 1745568428138,
            "status": "RUNNING",
            "task_id": "50e2ccea-abc4-43d7-a0dc-xxxxxx",
            "user_api_unique_key": "apikey:v1:aigc:image2video:video-synthesis:wanx2.1-kf2v-plus"
        },
        {
            "api_key_id": "15xxxx",
            "caller_parent_id": "xxxxxxxxx",
            "caller_uid": "xxxxxxxxx",
            "end_time": 1745568302481,
            "gmt_create": 1745568293253,
            "model_name": "wanx2.1-t2i-turbo",
            "region": "cn-beijing",
            "request_id": "f6bf34d9-bf87-9e8b-9ed4-xxxxxx",
            "start_time": 1745568293273,
            "status": "SUCCEEDED",
            "task_id": "3c777dbc-8cc6-4d80-aa90-xxxxxx",
            "user_api_unique_key": "apikey:v1:aigc:text2image:image-synthesis:wanx2.1-t2i-turbo"
        }
    ],
    "total_page": 1,
    "page_no": 1,
    "request_id": "f6756b7e-d0bb-9b74-813a-xxxxxx",
    "page_size": 10
}

Annuler une tâche asynchrone

Description de l'API : Annule une tâche asynchrone. Seules les tâches dont le statut est PENDING (en file d'attente, non démarrées) peuvent être annulées. Limite de débit : 20 QPS par compte Alibaba Cloud (inclut tous les utilisateurs RAM).
  • Vous pouvez annuler n'importe quelle tâche associée au compte Alibaba Cloud propriétaire de la clé API actuelle, y compris les tâches soumises avec n'importe quelle clé API sous ce compte. Vous ne pouvez pas annuler les tâches provenant d'autres comptes.

Endpoint de requête

POST https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}/cancel

Paramètres de requête

Passage des paramètres

Champ

Type

Obligatoire

Description

Exemple

Header

Authorization

String

Oui

La clé API, au format Bearer sk-xxx.

Bearer sk-xxx

Path

task_id

String

Oui

L'ID de la tâche à annuler.

a8532587-xxxx-xxxx-xxxx-0c46b17950d1

Paramètres de réponse

Une demande d'annulation réussie renvoie l'ID de la requête sous forme de chaîne JSON brute dans le corps de la réponse. La réponse de succès ne contient aucun champ d'objet JSON. Pour les réponses d'erreur, les champs suivants sont renvoyés :

Champ

Type

Description

Exemple

code

String

Le code d'erreur renvoyé en cas d'échec de l'appel.

"code": "Throttling.RateQuota"

message

String

Le message d'erreur renvoyé en cas d'échec de l'appel.

"message": "Requests rate limit exceeded, please try again later."

Exemple de requête

curl -X POST 'https://dashscope.aliyuncs.com/api/v1/tasks/73205176-xxxx-xxxx-xxxx-16bd5d902219/cancel' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Exemple de réponse

"45ac7f13-xxxx-xxxx-xxxx-e03c35068d83"

Codes d'erreur

Code d'état HTTP

Code d'erreur

Message d'erreur

Description

400

UnsupportedOperation

Échec de l'annulation de la tâche. Vérifiez que la tâche est bien au statut PENDING.

L'annulation de la tâche a échoué. Seules les tâches dont le statut est PENDING peuvent être annulées.