Manage asynchronous tasks

Some models (like image and video generation) run asynchronously: you create a task, get an ID, then query the result with that ID. Use these APIs to query results, check status in batches, and cancel queued tasks.

Prerequisites

Call these APIs over HTTP. Get an API key, then set it as an environment variable.

Query the result of an asynchronous task

API description: Query a task's status and result by task_id. Rate limit: 20 QPS per QwenCloud account.

You can query all tasks under the QwenCloud account that owns the API key, including tasks from any API key under that account. You cannot query tasks from other accounts.
Completed task data is retained for 24 hours by default (check the specific API reference for the exact duration) before automatic deletion.

Request endpoint

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
GET https://ap-southeast-1.maas.qwencloudapi.com/api/v1/tasks/{task_id}

Request parameters

Parameter passing	Field	Type	Required	Description	Example
Header	Authorization	String	Yes	The API key, in the format Bearer sk-ws-xxx.	Bearer sk-ws-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	Contains the result on success or the error code and message on failure. For multi-subtask requests, may include both results and errors.	-
output.task_id	String	The queried task ID.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1
output.task_status	String	The task status. A multi-subtask job is marked SUCCEEDED if at least one subtask succeeds. Failed subtasks show their errors in the output.	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 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 on failure.	-
output.message	String	The error message. Returned only on failure.	-
output.task_metrics	Object	Subtask status statistics.	`{ "TOTAL": 4, "SUCCEEDED": 3, "FAILED": 1 }`
usage	Object	Billing information for this request. Varies by task type.	`"usage": {"image_count": 1}`

Request example

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X GET 'https://ap-southeast-1.maas.qwencloudapi.com/api/v1/tasks/73205176-xxxx-xxxx-xxxx-16bd5d902219' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

If you haven't set the API key as an environment variable, replace $DASHSCOPE_API_KEY with your actual key. Example: --header "Authorization: Bearer sk-ws-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 the status of multiple tasks at once by time range, model, or status. Rate limit: 20 QPS per QwenCloud account.

You can query all tasks under the QwenCloud account that owns the API key, including tasks from any API key under that account. You cannot query tasks from other accounts.
Completed task data is retained for 24 hours by default (check the specific API reference for the exact duration) before automatic deletion.

Request endpoint

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
GET https://ap-southeast-1.maas.qwencloudapi.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-ws-xxx.	Bearer sk-ws-xxx
Params	task_id	String	No	A specific task ID. If set, only that task is returned. Omit to query multiple tasks.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1
Params	start_time	String	No	Start time (format: YYYYMMDDhhmmss). Defaults to 24 hours before end_time, or the last 24 hours if end_time is also omitted. Range cannot exceed 24 hours.	20230420193058 represents 19:30:58 on April 20, 2023.
Params	end_time	String	No	End time (format: YYYYMMDDhhmmss). Defaults to 24 hours after start_time. Range cannot exceed 24 hours.	20230420193058 represents 19:30:58 on April 20, 2023.
Params	model_name	String	No	The model name.	wan2.6-t2v
Params	status	String	No	The task status: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, UNKNOWN
Params	page_no	Integer	No	The page number. Default: 1.	-
Params	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.	See example below
data[].api_key_id	String	The API key ID.	See example below
data[].caller_parent_id	String	The QwenCloud account ID.	See example below
data[].caller_uid	String	The QwenCloud account UID.	See example below
data[].gmt_create	Long	The task creation time in milliseconds since the epoch.	See example below
data[].start_time	Long	The task start time in milliseconds since the epoch.	See example below
data[].end_time	Long	The task end time in milliseconds since the epoch.	See example below
data[].region	String	The region.	See example below
data[].request_id	String	The request ID for the task submission.	See example below
data[].status	String	The task status: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, UNKNOWN	See example below
data[].task_id	String	The task ID.	See example below
data[].user_api_unique_key	String	A unique index derived from the model's API parameters at submission.	See example below
data[].model_name	String	The model name.	See example below
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 only on failure.	`"code": "Throttling.RateQuota"`
message	String	The error message. Returned only on failure.	`"message": "Requests rate limit exceeded, please try again later."`

Request example

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X GET 'https://ap-southeast-1.maas.qwencloudapi.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": "ap-southeast-1",
      "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": "ap-southeast-1",
      "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: Cancel a task in PENDING state. Tasks in other states cannot be canceled. Rate limit: 20 QPS per QwenCloud account.

You can cancel any task under the QwenCloud account that owns the API key, including tasks from any API key under that account. You cannot cancel tasks from other accounts.

Request endpoint

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
POST https://ap-southeast-1.maas.qwencloudapi.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-ws-xxx.	Bearer sk-ws-xxx
Path	task_id	String	Yes	The task ID to cancel.	a8532587-xxxx-xxxx-xxxx-0c46b17950d1

Current successful cancellation returns a JSON string containing the request ID. The object response table and example below are historical. Error responses still use the code and message fields.

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 only on failure.	`"code": "Throttling.RateQuota"`
message	String	The error message. Returned only on failure.	`"message": "Requests rate limit exceeded, please try again later."`

Request example

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST 'https://ap-southeast-1.maas.qwencloudapi.com/api/v1/tasks/73205176-xxxx-xxxx-xxxx-16bd5d902219/cancel' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response example

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

SDK and CLI task management

Python SDK

The asynchronous task API is independent of the task type. The fetch, list, and cancel methods can be called on any asynchronous task resource (such as client.images.jobs, client.videos.jobs, client.audio.asr.jobs, etc.). They all request /api/v1/tasks under the hood and can query any task under the current account.

import os
import dashscope

# If you have not set an environment variable, replace the following line with your QwenCloud API key: api_key="sk-xxx"
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = dashscope.Client(api_key=os.getenv('DASHSCOPE_API_KEY'), region="ap-southeast-1", base_url="https://ap-southeast-1.maas.qwencloudapi.com/api/v1")

task_id = '73205176-xxxx-xxxx-xxxx-16bd5d902219'
job = client.images.jobs.fetch(task_id)
print(job.status, job.results)

dashscope CLI

Call via the dashscope command line.

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
export DASHSCOPE_API_KEY="your-api-key"
export DASHSCOPE_HTTP_BASE_URL="https://ap-southeast-1.maas.qwencloudapi.com/api/v1"
# Query task status (e.g., video-synthesis)
dashscope video-synthesis fetch <task_id>

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

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

Python SDK

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
import os
import dashscope

# If you have not set an environment variable, replace the following line with your QwenCloud API key: api_key="sk-xxx"
client = dashscope.Client(api_key=os.getenv('DASHSCOPE_API_KEY'), region="ap-southeast-1", base_url="https://ap-southeast-1.maas.qwencloudapi.com/api/v1")

page = client.images.jobs.list(
    start_time='20230420193000',
    end_time='20230420203000',
    status='RUNNING',
    page_no=1,
    page_size=10,
)
print(page.total, page.tasks)

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

fetch, list, and cancel use the configured QwenCloud regional Base URL. Use an API key for that same region; changing the Base URL does not make API keys valid across regions.

dashscope CLI

Call via the dashscope command line.

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
export DASHSCOPE_API_KEY="your-api-key"
export DASHSCOPE_HTTP_BASE_URL="https://ap-southeast-1.maas.qwencloudapi.com/api/v1"
# List video synthesis tasks (supports --start-time/--end-time/--status/--model-name filters)
dashscope video-synthesis list --status RUNNING -s 10

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

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

Python SDK

import os
import dashscope

# If you have not set an environment variable, replace the following line with your QwenCloud API key: api_key="sk-xxx"
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = dashscope.Client(api_key=os.getenv('DASHSCOPE_API_KEY'), region="ap-southeast-1", base_url="https://ap-southeast-1.maas.qwencloudapi.com/api/v1")

task_id = '73205176-xxxx-xxxx-xxxx-16bd5d902219'
job = client.images.jobs.cancel(task_id)
print(job)

Only tasks with PENDING status can be canceled. Calling on tasks in other states raises a DashScopeError exception (UnsupportedOperation).

dashscope CLI

Call via the dashscope command line.

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
export DASHSCOPE_API_KEY="your-api-key"
export DASHSCOPE_HTTP_BASE_URL="https://ap-southeast-1.maas.qwencloudapi.com/api/v1"
# Cancel task (e.g., video-synthesis, only PENDING status can be canceled)
dashscope video-synthesis cancel <task_id>

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

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

Current cancellation response

The current source documents a successful cancellation response as a JSON string containing the request ID. The object response example above is retained as a historical example; use the string format below for the current API.

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

Cancellation response source discrepancy

The EN source documents a JSON request ID string, while the ZH source documents a request_id object for the same operation. The API panel preserves both documented shapes. The earlier object example below is retained; confirm the actual response shape for your service before parsing it.

Source task-list fragment (not a standalone JSON response)

"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"
    }
]

​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

​SDK and CLI task management

​Python SDK

​dashscope CLI

​Python SDK

​dashscope CLI

​Python SDK

​dashscope CLI

​Current cancellation response

​Cancellation response source discrepancy

​Source task-list fragment (not a standalone JSON response)

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

SDK and CLI task management

Python SDK

dashscope CLI

Python SDK

dashscope CLI

Python SDK

dashscope CLI

Current cancellation response

Cancellation response source discrepancy

Source task-list fragment (not a standalone JSON response)