POST /maestro/videos)返回的任務 ID,查詢該任務的執行狀態與最終結果。
本文檔將詳細介紹 Maestro 任務查詢 API 的串接說明。由於影片生成是一個非同步任務,提交後需要使用本介面輪詢取得進度與成片,輪詢免費、不消耗點數。
POST https://api.acedata.cloud/maestro/tasks
申請流程
要使用 Maestro 任務查詢 API,首先到 Ace Data Cloud 控制台 取得您的 API Token,留作備用。
如果你尚未登入或註冊,會自動跳轉到登入頁面邀請你註冊和登入,完成後會自動返回目前頁面。
一個 API Token 即可呼叫平台所有服務,無需為每個服務個別申請。 首次申請會贈送免費額度,可免費體驗;額度不足時可在 控制台 儲值通用餘額。
📘 完整文件:Maestro 任務查詢 API →
查詢單一任務
關於如何建立影片任務,請參考文件 Maestro 影片生成 API。我們以其返回的一個任務 ID 為例:f57e99c4f60f4373a15517742ce2357d,示範如何查詢它的狀態與結果。
設定請求標頭和請求主體
Request Headers 包括:accept:指定接收 JSON 格式的回應結果,這裡填寫為application/json。authorization:呼叫 API 的金鑰,申請之後可以直接下拉選擇。content-type:請求主體的格式,這裡填寫為application/json。
程式碼範例
對應的 CURL 程式碼如下:回應範例
請求成功後,API 將回傳該影片任務的狀態與結果。任務完成時的回傳範例如下(variants 陣列中包含一支成片):
id:此影片任務的 ID,用於唯一識別本次影片生成任務。status:任務狀態,值為pending → planning → producing → succeeded(或failed)。任務是否已完成,應以此頂層status為準。elapsed:任務已耗時(秒)。progress:頂層進度物件,percent(0–100)在任務成功後為 100;stage與message反映 AI 導演最近一則進度事件(因此成功後stage可能仍為最後一個執行階段,例如producing),可直接用於顯示進度列。request:發起任務時的請求本文。response:任務的回傳資訊。success:任務是否成功。data.variants:包含一個所選語言的成片物件,包含lang、aspect、title、output_url(成片下載網址)等。data.project:整個專案產物,包含tarball_url(專案套件)與outputs(成片連結)。data.progress:依階段追加的進度事件陣列(append-only 日誌),可用於顯示詳細的即時進度。
created_at:任務建立時間,Unix 時間戳記(秒)。started_at:任務開始執行時間,Unix 時間戳記(秒)。任務尚未開始時為 null。finished_at:任務完成時間,Unix 時間戳記(秒)。任務未完成時為 null。
查詢歷史列表
傳入action: retrieve_batch 即可取得目前登入執行者最近的任務(按建立時間倒序),可用於「我的影片」列表頁。歷史列表按登入身分隔離。
Request Body 包括:
程式碼範例
對應的 CURL 程式碼如下:回應範例
請求成功後,API 將回傳目前使用者的歷史任務列表:count:目前登入執行者可見的任務總數,不受時間條件或limit影響。items:經過時間條件與limit篩選的任務陣列,按建立時間倒序排列;每個元素的格式與「查詢單一任務」的回傳結果一致。
輪詢建議
由於影片生成耗時較長,status 會經歷 pending → planning → producing → succeeded(或 failed)。建議每 5–10 秒輪詢一次,直到 status 變為 succeeded 或 failed 為止。可藉助頂層 progress.percent 顯示即時進度條。輪詢本介面免費,不消耗點數。
錯誤處理
在呼叫 API 時,如果遇到錯誤,API 會回傳相應的錯誤代碼和資訊。例如:401 invalid_token:未授權,授權權杖無效或缺失。404 not_found:找不到任務,指定的 task_id 不存在。429 too_many_requests:請求過多,您已超過速率限制。500 api_error:內部伺服器錯誤,伺服器發生異常。
錯誤回應範例
結論
透過本文檔,您已經了解如何使用 Maestro 任務查詢 API 查詢單一任務的狀態與結果,以及取得目前使用者的歷史任務列表。希望本文檔能幫助您更好地串接和使用該 API。如有任何問題,請隨時聯絡我們的技術支援團隊。相關介面
- Maestro 影片生成 API 串接說明:使用一句自然語言提示詞自動生成帶字幕的成片,提交後回傳
task_id,再使用本介面輪詢結果。

