跳转到主要内容
千问云 home page
开放平台文档
更多

异步任务管理 API 参考

通过 HTTP API 查询单个异步任务结果、批量查询异步任务状态、以及取消异步任务的完整参考文档。

本文档介绍异步任务管理 HTTP API 的完整参数与使用方法。在使用前，请确保已获取 API Key。所有接口的基础路径为： 
https://dashscope.aliyuncs.com/api/v1/tasks
Windows CMD 请将 $DASHSCOPE_API_KEY 替换为 %DASHSCOPE_API_KEY%，PowerShell 请替换为 $env:DASHSCOPE_API_KEY。

查询异步任务结果

查询指定异步任务的执行结果。接口 QPS 限制为 20 次/账号，任务完成后结果保留 24 小时。 
curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

输入参数

字段类型传参方式必选描述
AuthorizationStringHeader是API Key，格式为 Bearer sk-xxx。
task_idStringUrl Path是要查询的异步任务 ID。

返回样例

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

返回参数

参数名称类型参数说明
request_idString本次请求的 ID。
outputObject任务详情。
output.task_idString异步任务 ID。
output.task_statusString任务状态，详见任务状态。
output.submit_timeString任务提交时间。
output.scheduled_timeString任务开始调度时间。
output.end_timeString任务结束时间。
output.codeString任务失败时的错误码。
output.messageString任务失败时的错误信息。
output.task_metricsObject子任务统计信息，格式为 {"TOTAL": N, "SUCCEEDED": N, "FAILED": N}。
usageObject资源用量，具体字段因任务类型不同而有所差异。
对于包含多个子任务的批量任务，只要有一个子任务成功，整体任务状态即为 SUCCEEDED。请通过 output.task_metrics 中的 FAILED 字段确认是否存在失败的子任务。

批量查询异步任务状态

查询当前账号下的异步任务列表及其状态。接口 QPS 限制为 20 次/账号，仅可查询本账号下的任务。 
curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/?start_time=xxx&end_time=xxx&status=xxx' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

输入参数

字段类型传参方式必选描述
AuthorizationStringHeader是API Key，格式为 Bearer sk-xxx。
start_timeStringQuery否查询起始时间，格式为 YYYYMMDDhhmmss。若不填，默认为 end_time 前 24 小时；若两者均不填，默认查询最近 24 小时的任务。start_time 与 end_time 的时间差不能超过 24 小时。
end_timeStringQuery否查询截止时间，格式为 YYYYMMDDhhmmss。
model_nameStringQuery否按模型名称过滤。
statusStringQuery否按任务状态过滤，详见任务状态。
page_noIntegerQuery否页码，默认值为 1。
page_sizeIntegerQuery否每页数据量，默认值为 10。

返回样例

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

返回参数

参数名称类型参数说明
request_idString本次请求的 ID。
totalInteger满足条件的任务总数量。
total_pageInteger总页数。
page_noInteger当前页码。
page_sizeInteger每页数据量。
dataArray任务列表。
data[].task_idString异步任务 ID。
data[].statusString任务状态，详见任务状态。
data[].model_nameString任务使用的模型名称。
data[].gmt_createLong任务创建时间（毫秒时间戳）。
data[].start_timeLong任务开始时间（毫秒时间戳）。
data[].end_timeLong任务结束时间（毫秒时间戳）。
data[].request_idString提交任务时的请求 ID。
data[].regionString任务所在地域，例如 cn-hangzhou。
data[].api_key_idString提交任务使用的 API Key ID。
data[].caller_parent_idString千问云账号 ID。
data[].caller_uidString千问云账号 ID。
data[].user_api_unique_keyString提交任务的 API 唯一标识。
codeString请求失败时的错误码。
messageString请求失败时的错误信息。

取消异步任务

取消指定的异步任务。接口 QPS 限制为 20 次/账号。
只有处于 PENDING（排队等待）状态的任务可以被取消，已开始执行的任务无法取消。同一主账号下，任意 API Key 提交的任务均可取消。
curl -X POST 'https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}/cancel' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

输入参数

字段类型传参方式必选描述
AuthorizationStringHeader是API Key，格式为 Bearer sk-xxx。
task_idStringUrl Path是要取消的异步任务 ID。

返回样例

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

返回参数

参数名称类型参数说明
request_idString本次请求的 ID。
codeString取消失败时的错误码。
messageString取消失败时的错误信息。

任务状态

任务状态含义
PENDING任务排队等待中，尚未开始执行。
RUNNING任务正在执行中。
SUCCEEDED任务执行成功。
FAILED任务执行失败。
CANCELED任务已取消。
UNKNOWN任务状态未知。

错误码

HTTP 状态码错误码错误信息举例含义处理方式
400UnsupportedOperationFailed to cancel the task, please confirm if the task is in PENDING status.任务当前状态不支持取消操作。确认任务处于 PENDING 状态后再进行取消。