> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Maestro 任務查詢 API 串接說明

> Maestro AI Video Studio 整合指南 - Ace Data Cloud

Maestro 任務查詢 API 的主要功能是透過 [Maestro 影片生成 API](/zh-Hant/guides/maestro/maestro_videos)（`POST /maestro/videos`）回傳的任務 ID，查詢該任務的執行狀態與最終結果。

本文檔將詳細介紹 Maestro 任務查詢 API 的串接說明。由於影片生成是一個非同步任務，提交後需要使用本介面輪詢取得進度與成片，**輪詢免費、不消耗點數。**

`POST https://api.acedata.cloud/maestro/tasks`

## 申請流程

要使用 Maestro 任務查詢 API，首先前往 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 取得您的 API Token，留作備用。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

如果你尚未登入或註冊，會自動跳轉到登入頁面邀請你註冊和登入，完成後會自動返回目前頁面。

**一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。

> 📘 完整文件：[Maestro 任務查詢 API →](https://platform.acedata.cloud/documents/maestro-tasks)

## 查詢單一任務

關於如何建立影片任務，請參考文件 [Maestro 影片生成 API](/zh-Hant/guides/maestro/maestro_videos)。我們以其回傳的一個任務 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 程式碼如下：

```bash theme={null}
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 程式碼如下：

```python theme={null}
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`）：

```json theme={null}
{
  "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 程式碼如下：

```bash theme={null}
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 將回傳目前使用者的歷史任務清單：

```json theme={null}
{
  "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`：內部伺服器錯誤，伺服器發生問題。

### 錯誤回應範例

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

## 結論

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

## 相關介面

* [Maestro 影片生成 API 串接說明](/zh-Hant/guides/maestro/maestro_videos)：用一句自然語言提示詞自動生產帶字幕的成片，提交後回傳 `task_id`，再使用本介面輪詢結果。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.