How to query and cancel asynchronous tasks? - Alibaba Cloud Model Studio

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

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"

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

Python SDK

The asynchronous task interface is independent of the specific task type. The fetch, list, and cancel methods can be called on any asynchronous task class (such as ImageSynthesis, VideoSynthesis, Transcription, etc.). They all request /api/v1/tasks and can query any task under the current account.

import os
from dashscope import ImageSynthesis

task_id = '73205176-xxxx-xxxx-xxxx-16bd5d902219'
resp = ImageSynthesis.fetch(
    task_id,
    api_key=os.getenv('DASHSCOPE_API_KEY'),
)
print(resp.output)

dashscope CLI

Call via the dashscope command line.

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, ap-southeast-1 with your region (e.g., us-east-1, eu-central-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# Query task status (e.g., video-synthesis)
dashscope video-synthesis fetch <task_id>

NoteThe dashscope CLI currently supports fetch/list/cancel task management only for the video-synthesis subcommand; image-synthesis, transcription, and other subcommands are not yet supported. To query other task types, use the Python SDK or curl above.

ImportantThe SDK Expert interactive assistant can accomplish the same development and troubleshooting via natural language, see

DashScope SDK Expert.

For the complete region table, see Base URL overview.

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

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

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.	20230420193058 represents 19:30:58 on April 20, 2023.
	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.	`"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

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

Python SDK

import os
from dashscope import ImageSynthesis

resp = ImageSynthesis.list(
    start_time='20230420193000',
    end_time='20230420203000',
    status='RUNNING',
    page_no=1,
    page_size=10,
    api_key=os.getenv('DASHSCOPE_API_KEY'),
)
print(resp.output)

list also supports filtering by model_name, api_key_id, region, etc. The parameters correspond one-to-one with the HTTP API Query parameters.

Notefetch, list, and cancel are supported on both workspace-specific domains ({WorkspaceId}.{region}.maas.aliyuncs.com) and the general domain (dashscope.aliyuncs.com), and can be called across regions. The API Key must match the corresponding workspace.

dashscope CLI

Call via the dashscope command line.

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, ap-southeast-1 with your region (e.g., us-east-1, eu-central-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# List video synthesis tasks (supports --start-time/--end-time/--status/--model-name filters)
dashscope video-synthesis list --status RUNNING -s 10

NoteThe dashscope CLI currently supports task management only for the video-synthesis subcommand; to query other task types (image, transcription, etc.), use the Python SDK or curl above.

ImportantThe SDK Expert interactive assistant can accomplish the same development and troubleshooting via natural language, see

DashScope SDK Expert.

For the complete region table, see Base URL overview.

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

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

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"

Python SDK

import os
from dashscope import ImageSynthesis

task_id = '73205176-xxxx-xxxx-xxxx-16bd5d902219'
resp = ImageSynthesis.cancel(
    task_id,
    api_key=os.getenv('DASHSCOPE_API_KEY'),
)
print(resp)

Only tasks with PENDING status can be canceled; other statuses will return a failure.

dashscope CLI

Call via the dashscope command line.

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, ap-southeast-1 with your region (e.g., us-east-1, eu-central-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# Cancel task (e.g., video-synthesis, only PENDING status can be canceled)
dashscope video-synthesis cancel <task_id>

NoteThe dashscope CLI currently supports cancel only for the video-synthesis subcommand; to cancel other task types, use the Python SDK or curl above.

ImportantThe SDK Expert interactive assistant can accomplish the same development and troubleshooting via natural language, see

DashScope SDK Expert.

For the complete region table, see Base URL overview.

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.