Skip to main content
更多

非同步任務管理 API

阿里雲百鍊的部分模型（如映像產生、視頻產生等）因處理時間較長，採用非同步呼叫機制，通常需要調用兩個介面完成操作：先建立任務擷取 ID，再通過該 ID 查詢結果。為了方便管理非同步任務，阿里雲百鍊提供了一組通用的非同步任務介面，支援查詢單個任務結果、批量查詢多個任務狀態、以及取消正在排隊且尚未處理的任務。

前提條件

非同步任務API通過HTTP進行調用。 在調用前，您需要擷取與配置 API Key，再配置API Key到環境變數。

查詢非同步任務結果介面

API描述：根據任務ID（task_id）查詢任務狀態和任務結果。 流量限制：20 QPS，即每秒每個帳號（含主帳號及其子帳號）最多發起 20 次請求。
  • 支援查詢當前 API Key 所屬阿里雲主帳號下的所有任務（包括該主帳號下通過任意 API Key 提交的任務），但無法查詢其他主帳號提交的任務。
  • 非同步任務在完成後通常保留 24 小時 （具體以對應任務的 API 文檔為準），逾時後系統將自動清理歷史任務資料。
查詢任務結果的次數不影響任務的執行。建議根據任務類型合理設定查詢間隔：
  • 較快的任務（如文本向量）可以使用較短的查詢間隔。
  • 較慢的任務（如映像產生、視頻產生）建議使用較長的查詢間隔。
  • 避免過於頻繁地查詢任務狀態，以防觸發限流（20 QPS）。

請求介面 

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks{task_id}

入參描述

傳參方式

欄位

類型

必選

描述

樣本值

Header

Authorization

String

是

API-Key，例如：Bearer sk-xxx

Bearer sk-xxx

Path

task_id

String

是

需查詢的任務ID

a8532587-xxxx-xxxx-xxxx-0c46b17950d1

出參描述

欄位

類型

描述

樣本值

request_id

String

本次請求的系統唯一碼

7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51

output

Object

  • 任務成功時，output 包含模型產生的結果對象，具體內容因任務類型而異

  • 任務失敗或部分失敗時，output 會返回對應的 code 和 message，說明失敗原因

  • 對於包含多個子任務的任務，output 可能同時包含成功的子任務結果和失敗的錯誤資訊

-

output.task_id

String

查詢任務的 task_id

a8532587-xxxx-xxxx-xxxx-0c46b17950d1

output.task_status

String

任務狀態

  • 對於包含多個子任務的任務，只要有一個子任務成功，整個任務會被標記為成功

  • 對於失敗的子任務，會在 output 中展示具體報錯

任務狀態：

  • PENDING：任務排隊中

  • RUNNING：任務處理中

  • SUCCEEDED：任務執行成功

  • FAILED：任務執行失敗

  • UNKNOWN：任務不存在或狀態未知

output.submit_time

String

任務提交時間

2023-12-20 21:36:31.896

output.scheduled_time

String

任務調度時間，即開始執行時間

2023-12-20 21:36:39.009

output.end_time

String

任務結束時間

2023-12-20 21:36:45.913

output.code

String

錯誤碼，僅在任務失敗時返回

-

output.message

String

錯誤資訊，僅任務失敗時返回

-

output.task_metrics

Object

任務指標，包含子任務狀態的統計資訊

{

"TOTAL": 4, //子任務總數

"SUCCEEDED": 3, //子任務成功數

"FAILED": 1 //子任務失敗數

}

usage

Object

本次請求產生的計量資訊，根據實際任務的不同，相關的計量資訊也有所不同

"usage": {"image_count": 1}

請求樣本 

curl -X GET 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks73205176-xxxx-xxxx-xxxx-16bd5d902219' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
若未配置阿里雲百鍊API Key到環境變數，請將$DASHSCOPE_API_KEY替換為實際API Key，例如：--header "Authorization: Bearer sk-xxx"。

響應樣本 

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

批量查詢非同步任務狀態介面

API描述：支援通過組合多種查詢條件，批量擷取多個非同步任務的目前狀態。該介面適用於一次性查看多個任務的執行進度。 流量限制：20 QPS，即每秒每個帳號（含主帳號及其子帳號）最多發起 20 次請求。
  • 支援查詢當前 API Key 所屬阿里雲主帳號下的所有任務（包括該主帳號下通過任意 API Key 提交的任務），但無法查詢到其他主帳號下的任務。
  • 已結束的任務在逾時後將被系統自動清理，屆時將無法查詢到相關任務資料。

請求介面 

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks

入參描述

傳參方式

欄位

類型

必選

描述

樣本值

Header

Authorization

String

是

API-Key，例如：Bearer sk-xxx

Bearer sk-xxx

Params

task_id

String

否

需要查詢任務的 task_id

若指定task_id，介面僅返回該任務的狀態資訊；若需批量查詢多個任務狀態，請勿傳入此參數

a8532587-xxxx-xxxx-xxxx-0c46b17950d1

start_time

String

否

任務開始時間，格式為：YYYYMMDDhhmmss

  • 若未指定開始時間（start_time為空白），系統將查詢指定結束時間（end_time）前24小時的資料

  • 若開始和結束時間均未指定（均為空白），系統預設查詢最近24小時的資料。

  • 請確保您設定的開始和結束時間的差距不超過24小時

20230420193058 代表 2023 年 4 月 20 日 19 點 30 分 58 秒

end_time

String

否

任務結束時間，格式為：YYYYMMDDhhmmss

  • 若未指定結束時間（end_time為空白），系統將查詢指定開始時間（start_time）後24小時的資料。

  • 請確保您設定的開始和結束時間的差距不超過24小時

model_name

String

否

模型名稱

wanx-v1

status

String

否

任務狀態：

  • PENDING：任務排隊中

  • RUNNING：任務處理中

  • SUCCEEDED：任務執行成功

  • FAILED：任務執行失敗

  • CANCELED：任務取消成功

  • UNKNOWN：任務不存在或狀態未知

page_no

Integer

否

當前頁，預設查詢第1頁

-

page_size

Integer

否

每頁查詢條數，預設查詢10條

-

出參描述

欄位類型描述樣本值
request_idString本次請求的系統唯一碼7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
dataArray查詢結果清單
"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_idStringAPI Key的id
data[].caller_parent_idString阿里雲主帳號ID
data[].caller_uidString阿里雲帳號ID
data[].gmt_createLong任務建立時間，Date時間毫秒數
data[].start_timeLong任務開始時間，Date時間毫秒數
data[].end_timeLong任務結束時間，Date時間毫秒數
data[].regionString地區，例如：cn-hangzhou
data[].request_idString提交任務的請求id
data[].statusString任務狀態：
  • PENDING：任務排隊中
  • RUNNING：任務處理中
  • SUCCEEDED：任務執行成功
  • FAILED：任務執行失敗
  • CANCELED：任務取消成功
  • UNKNOWN：任務不存在或狀態未知
data[].task_idString任務id
data[].user_api_unique_keyStringAPI 的唯一key（提交任務時，模型API的各要素唯一索引）
data[].model_nameString模型名稱
page_noInteger當前頁"page_no": 1
page_sizeInteger每頁查詢條數"page_size": 10
total_pageInteger總頁數"total_page": 4
totalInteger總條數"total": 39
codeString調用失敗的時候返回的錯誤碼"code": "Throttling.RateQuota"
messageString調用失敗的時候返回的錯誤資訊"message": "Requests rate limit exceeded, please try again later."

請求樣本 

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

響應樣本 

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

取消非同步任務介面

API描述：用於取消非同步任務，僅支援取消狀態為 PENDING 的任務 （即排隊中且尚未開始處理的任務），其他狀態的任務無法取消。 流量限制：20 QPS，即每秒每個帳號（含主帳號及其子帳號）最多發起 20 次請求。
  • 支援取消當前 API Key 所屬阿里雲主帳號下的所有任務（包括該主帳號下通過任意 API Key 提交的任務），但無法取消其他主帳號提交的任務。

請求介面 

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks{task_id}/cancel

入參描述

傳參方式

欄位

類型

必選

描述

樣本值

Header

Authorization

String

是

API-Key，例如：Bearer sk-xxx

Bearer sk-xxx

Path

task_id

String

是

待取消的任務 task_id

a8532587-xxxx-xxxx-xxxx-0c46b17950d1

出參描述

欄位

類型

描述

樣本值

request_id

String

本次請求的系統唯一碼

7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51

code

String

調用失敗的時候返回的錯誤碼

"code": "Throttling.RateQuota"

message

String

調用失敗的時候返回的錯誤資訊

"message": "Requests rate limit exceeded, please try again later."

請求樣本 

curl -X POST 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks73205176-xxxx-xxxx-xxxx-16bd5d902219/cancel' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

響應樣本 

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

錯誤碼

HTTP狀態代碼

介面錯誤碼（code）

介面錯誤資訊（message）

含義說明

400

UnsupportedOperation

Failed to cancel the task, please confirm if the task is in PENDING status.

取消任務失敗，請確認任務狀態為PENDING。

僅 PENDING 狀態的任務可取消，其他狀態任務無法取消。

常見問題

任務查詢返回 DataInspectionFailed 錯誤碼是什麼含義？

DataInspectionFailed 表示輸出資料可能包含不適當的內容，已被Alibaba Content Security Service審核攔截。對於包含多個子任務的非同步任務（如批量映像產生），部分子任務可能返回此錯誤碼，而其他子任務仍正常完成。此時整體任務狀態可能為 SUCCEEDED，但 task_metrics 中會顯示失敗的子任務數量。

如何判斷非同步任務是否執行完成？

通過查詢任務介面返回的 task_status 欄位判斷：
  • PENDING：任務排隊中，尚未開始處理。
  • RUNNING：任務處理中。
  • SUCCEEDED：任務執行成功。
  • FAILED：任務執行失敗，請查看 output 中的 code 和 message 瞭解失敗原因。

頻繁查詢任務狀態會影響任務執行嗎？

不會。查詢任務狀態的請求與任務執行是獨立的，查詢次數不影響任務的執行進度和結果。但請注意，查詢介面有 20 QPS 的限流限制，過於頻繁的查詢可能會觸發限流，返回錯誤響應。建議根據任務類型合理設定查詢間隔。
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
  • 概述
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多
非同步任務管理 API - Alibaba Cloud Model Studio