Asynchronous task management API

Some Model Studio models (like image and video generation) use asynchronous invocation due to long processing times. The typical workflow is: create a task to get an ID, then query the result using that ID. Model Studio provides general-purpose task APIs to query individual results, check multiple task statuses in batch, and cancel queued tasks.

Prerequisites

You can call the asynchronous task APIs over HTTP.

Before you call the APIs, get and configure an API key, and then set the API key as an environment variable.

Query the result of an asynchronous task

API description : Queries the status and result of a task based on its task_id.

Rate limit: 20 QPS per Alibaba Cloud account (includes all RAM users). Important

You can query all tasks under the Alibaba Cloud account that owns the current API key, including tasks submitted with any API key under that account. You cannot query tasks from other accounts.
Completed tasks are retained for 24 hours (check specific task API reference for exact period). After expiration, the system automatically deletes task data.

Request endpoint

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

Request parameters

Parameter passing	Field	Type	Required	Description	Example
Header	Authorization	String	Yes	API key in the format `Bearer sk-xxx`	Bearer sk-xxx
Path	task_id	String	Yes	The task ID to query.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1

Response parameters

Field	Type	Description	Example
request_id	String	The unique ID for this request.	7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
output	Object	- If the task succeeds, `output` contains the result object generated by the model. The content varies by task type. - If the task fails or partially fails, `output` returns the `code` and `message` fields that explain the failure reason. - For tasks with multiple subtasks, `output` may contain both successful subtask results and error messages for failed ones.	-
output.task_id	String	The ID of the queried task.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1
output.task_status	String	The task status. - For multi-subtask tasks, the task succeeds if at least one subtask succeeds. - Failed subtasks show specific errors in the output.	Task status: - PENDING - RUNNING - SUCCEEDED - FAILED - UNKNOWN
output.submit_time	String	The time the task was submitted.	2023-12-20 21:36:31.896
output.scheduled_time	String	The time the task was scheduled (when it started running).	2023-12-20 21:36:39.009
output.end_time	String	The time the task ended.	2023-12-20 21:36:45.913
output.code	String	The error code (returned only when the task fails).	-
output.message	String	The error message (returned only when the task fails).	-
output.task_metrics	Object	Task metrics including subtask status statistics.	`{` `"TOTAL": 4, // Total number of subtasks` `"SUCCEEDED": 3, // Number of successful subtasks` `"FAILED": 1 // Number of failed subtasks` `}`
usage	Object	The billing information for this request (varies by task).	`"usage": {"image_count": 1}`

Request example

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

Note

If $DASHSCOPE_API_KEY is not set as an environment variable, replace it with your actual API key (format: Bearer sk-xxx).

Response example

HELPCODEESCAPE-json
{
    "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
    }
}

Query the status of multiple asynchronous tasks

API description: Query multiple asynchronous tasks using various conditions. Check multiple task statuses in a single request.

Rate limit: 20 QPS per Alibaba Cloud account (includes all RAM users). Important

You can query all tasks under the Alibaba Cloud account that owns the current API key, including tasks submitted with any API key under that account. You cannot query tasks from other accounts.
After the retention period expires, the system deletes the task, and its data becomes unqueryable.

Request endpoint

HELPCODEESCAPE-http
GET https://dashscope.aliyuncs.com/api/v1/tasks/

Request parameters

Parameter passing	Field	Type	Required	Description	Example
Header	Authorization	String	Yes	The API key, in the format Bearer sk-xxx.	Bearer sk-xxx
Params	task_id	String	No	The task ID to query. Specify a task_id to return only that task's status, or omit it to query multiple tasks.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1
start_time	String	No	Query start time in the format `YYYYMMDDhhmmss`. Defaults to 24 hours before end_time (if end_time is specified), or to the last 24 hours (if neither time is specified). Maximum range: 24 hours.	20230420193058 represents 19:30:58 on April 20, 2023.
end_time	String	No	Query end time in the format `YYYYMMDDhhmmss`. Defaults to 24 hours after start_time (if start_time is specified). Maximum range: 24 hours.
model_name	String	No	The model name.	wanx-v1
status	String	No	The task status: - PENDING - RUNNING - SUCCEEDED - FAILED - CANCELED - UNKNOWN
page_no	Integer	No	The page number of the results to return. Default: 1.	-
page_size	Integer	No	The number of entries per page. Default: 10.	-

Response parameters

**Field**   **Type**   **Description**   **Example**           request_id   String   The unique ID for this request.   7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51     data   Array   A list of query results.

json

"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_id   String   The API key ID.     data\[\].caller_parent_id   String   The Alibaba Cloud account ID.     data\[\].caller_uid   String   The Alibaba Cloud account ID.     data\[\].gmt_create   Long   The task creation time (milliseconds since the epoch).     data\[\].start_time   Long   The time the task started, in milliseconds since the epoch.     data\[\].end_time   Long   The time the task ended, in milliseconds since the epoch.     data\[\].region   String   The region. Example: cn-hangzhou     data\[\].request_id   String   The request ID for the task submission.     data\[\].status   String   The task status:

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN data[].task_id String The task ID. data[].user_api_unique_key String A unique API key generated from the model's API parameters at task submission. data[].model_name String The model name. page_no Integer The current page number. "page_no": 1 page_size Integer The number of entries per page. "page_size": 10 total_page Integer The total number of pages. "total_page": 4 total Integer The total number of entries. "total": 39 code String The error code returned when the call fails. "code": "Throttling.RateQuota" message String The error message returned when the call fails. "message": "Requests rate limit exceeded, please try again later."

Request example

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

Response example

HELPCODEESCAPE-json
{
    "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
}

Cancel an asynchronous task

API description : Cancels an asynchronous task. Only tasks in PENDING state (queued, not started) can be canceled.

Rate limit: 20 QPS per Alibaba Cloud account (includes all RAM users). Important

You can cancel any task under the Alibaba Cloud account that owns the current API key, including tasks submitted with any API key under that account. You cannot cancel tasks from other accounts.

Request endpoint

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

Request parameters

Parameter passing	Field	Type	Required	Description	Example
Header	Authorization	String	Yes	The API key, in the format Bearer sk-xxx.	Bearer sk-xxx
Path	task_id	String	Yes	The ID of the task to cancel.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1

Response parameters

Field	Type	Description	Example
request_id	String	The unique ID for this request.	7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
code	String	The error code returned when the call fails.	`"code": "Throttling.RateQuota"`
message	String	The error message returned when the call fails.	`"message": "Requests rate limit exceeded, please try again later."`

Request example

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

Response example

HELPCODEESCAPE-json
{
    "request_id": "45ac7f13-xxxx-xxxx-xxxx-e03c35068d83"
}

Error codes

HTTP status code	Error code	Error message	Description
400	UnsupportedOperation	Failed to cancel the task. Confirm that the task is in PENDING status.	Task cancellation failed. Only tasks in `PENDING` state can be canceled.

Asynchronous task management API ​

Prerequisites ​

Query the result of an asynchronous task ​

Request endpoint ​

Request parameters ​

Response parameters ​

Request example ​

Response example ​

Query the status of multiple asynchronous tasks ​

Request endpoint ​

Request parameters ​

Response parameters ​

Request example ​

Response example ​

Cancel an asynchronous task ​

Request endpoint ​

Request parameters ​

Response parameters ​

Request example ​

Response example ​

Error codes ​

Asynchronous task management API

Prerequisites

Query the result of an asynchronous task

Request endpoint

Request parameters

Response parameters

Request example

Response example

Query the status of multiple asynchronous tasks

Request endpoint

Request parameters

Response parameters

Request example

Response example

Cancel an asynchronous task

Request endpoint

Request parameters

Response parameters

Request example

Response example

Error codes