Skip to main content
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
More

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).
  • 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 

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 

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/73205176-xxxx-xxxx-xxxx-16bd5d902219' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
If $DASHSCOPE_API_KEY is not set as an environment variable, replace it with your actual API key (format: Bearer sk-xxx).

Response example 

{
    "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).
  • 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 

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

FieldTypeDescriptionExample
request_idStringThe unique ID for this request.7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
dataArrayA list of query results.
"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_idStringThe API key ID.
data[].caller_parent_idStringThe Alibaba Cloud account ID.
data[].caller_uidStringThe Alibaba Cloud account ID.
data[].gmt_createLongThe task creation time (milliseconds since the epoch).
data[].start_timeLongThe time the task started, in milliseconds since the epoch.
data[].end_timeLongThe time the task ended, in milliseconds since the epoch.
data[].regionStringThe region. Example: cn-hangzhou
data[].request_idStringThe request ID for the task submission.
data[].statusStringThe task status:
  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN
data[].task_idStringThe task ID.
data[].user_api_unique_keyStringA unique API key generated from the model's API parameters at task submission.
data[].model_nameStringThe model name.
page_noIntegerThe current page number."page_no": 1
page_sizeIntegerThe number of entries per page."page_size": 10
total_pageIntegerThe total number of pages."total_page": 4
totalIntegerThe total number of entries."total": 39
codeStringThe error code returned when the call fails."code": "Throttling.RateQuota"
messageStringThe error message returned when the call fails."message": "Requests rate limit exceeded, please try again later."

Request example 

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 

{
    "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).
  • 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 

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

A successful cancel request returns the request ID as a plain JSON string in the response body. There are no JSON object fields in the success response. For error responses, the following fields are returned:

Field

Type

Description

Example

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 

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

Response example 

"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.

Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
Audio
Real-time Multimodal
Realtime API
Text Embedding
More Models
Toolkit/Framework
Model Production
File Management
More
Asynchronous task management API - Alibaba Cloud Model Studio