Maestro 任務查詢 API 串接說明

Maestro 任務查詢 API 的主要功能是透過 Maestro 影片生成 API（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。

Request Body 包括：

欄位	類型	必填	說明
`id`	string	查詢單一任務時必填	`POST /maestro/videos` 回傳的 `task_id`
`action`	string	否	`retrieve`（預設，查詢單一任務）；查詢歷史列表時固定為 `retrieve_batch`

程式碼範例

對應的 CURL 程式碼如下：

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "action": "retrieve"
}'

對應的 Python 程式碼如下：

import requests

url = "https://api.acedata.cloud/maestro/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

回應範例

請求成功後，API 將回傳該影片任務的狀態與結果。任務完成時的回傳範例如下（每種語言對應一個 variant）：

{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}

回傳結果的欄位介紹如下：

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 包括：

欄位	類型	必填	說明
`action`	string	是	固定為 `retrieve_batch`
`limit`	int	否	回傳筆數，預設 20；有效範圍為 1–100
`created_at_max`	int	否	只回傳嚴格早於該 Unix 時間戳記的任務（不含邊界值，用於分頁）
`created_at_min`	int	否	只回傳嚴格晚於該 Unix 時間戳記的任務（不含邊界值）

程式碼範例

對應的 CURL 程式碼如下：

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'

回應範例

請求成功後，API 將回傳目前使用者的歷史任務清單：

{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}

回傳結果的欄位說明如下：

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：內部伺服器錯誤，伺服器發生問題。

錯誤回應範例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

結論

透過本文檔，您已經瞭解如何使用 Maestro 任務查詢 API 查詢單一任務的狀態與結果，以及擷取目前使用者的歷史任務清單。希望本文檔能幫助您更好地串接和使用該 API。如有任何問題，請隨時聯絡我們的技術支援團隊。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

Coding

更多指南

Maestro 任務查詢 API 串接說明

申請流程

查詢單一任務

設定請求標頭和請求主體

程式碼範例

回應範例

查詢歷史列表

程式碼範例

回應範例

輪詢建議

錯誤處理

錯誤回應範例

結論

相關介面

​申請流程

​查詢單一任務

​設定請求標頭和請求主體

​程式碼範例

​回應範例

​查詢歷史列表

​程式碼範例

​回應範例

​輪詢建議

​錯誤處理

​錯誤回應範例

​結論

​相關介面

申請流程

查詢單一任務

設定請求標頭和請求主體

程式碼範例

回應範例

查詢歷史列表

程式碼範例

回應範例

輪詢建議

錯誤處理

錯誤回應範例

結論

相關介面