> ## 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 是一個 **Agent 原生** 的視頻生產接口：你用一句自然語言 `prompt` 描述想要的視頻（可選地用 `file_urls` 附上參考圖片 / 視頻 / 音頻），一個無頭的「AI 導演」會自動完成選題、寫腳本、生成畫面、配音、配樂、合成與渲染，最終產出帶字幕的成片並上傳 CDN。

本文將詳細介紹 Maestro 視頻生成 API 的對接說明，幫助您快速集成並充分利用該 API 的能力。

這是一個**異步任務**接口：提交後會立即返回 `task_id`，隨後通過 [Maestro 任務查詢 API](/zh-Hant/guides/maestro/maestro_tasks)（`POST /maestro/tasks`）輪詢獲取結果（輪詢免費不計費）。要在已有視頻上繼續迭代，可使用 `action: remix` / `edit` / `extend` 配合 `ref_task_id`。

## 申請流程

要使用 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-videos)

## 基本使用

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

最基礎的用法只需要傳入一個自然語言 `prompt`，AI 導演會自動決定腳本、畫面、配音與剪輯。這裡我們先了解下需要設置的請求頭與請求體。

**Request Headers** 包括：

* `accept`：想要接收怎樣格式的響應結果，這裡填寫為 `application/json`，即 JSON 格式。
* `authorization`：調用 API 的密鑰，申請之後可以直接下拉選擇。
* `content-type`：請求體的格式，這裡填寫為 `application/json`。

**Request Body** 主要包括：

* `prompt`：用自然語言描述要做的視頻（主題、要展示什麼、風格、受眾）。
* `langs`：輸出語言數組，如 `["zh-cn", "en"]`，默認 `["zh-cn"]`。
* `aspect`：畫面比例，`9:16`（默認）/ `16:9` / `1:1`。
* `duration`：目標時長（秒），默認 30。

請求體的全部字段如下表所示：

| 字段 | 類型 | 必填 | 說明 |
| - | - | - | - |
| `prompt` | string | 是 | 用自然語言描述要做的視頻（主題、要展示什麼、風格、受眾）。腳本、畫面、配音、剪輯都由 AI 決定 |
| `action` | string | 否 | `generate`（默認，生成新視頻）/ `remix` / `edit` / `extend`（在已有視頻上迭代，需配合 `ref_task_id`） |
| `ref_task_id` | string | 否 | 當 `action` 為 remix / edit / extend 時必填：作為起點的歷史任務 `task_id` |
| `file_urls` | string\[] | 否 | 參考媒體（圖片 / 視頻 / 音頻 URL），例如要出鏡的產品圖、logo，或要加字幕的素材片段 |
| `langs` | string\[] | 否 | 輸出語言，如 `["zh-cn", "en"]`，默認 `["zh-cn"]`。第一個為主語言；每多一種語言復用畫面、只多配音 + 渲染，**每多一種 +6 積分** |
| `aspect` | string | 否 | `9:16`（默認）/ `16:9` / `1:1`，統一輸出 1080p/30fps |
| `duration` | int | 否 | 目標時長（秒），默認 30，支持 **5–300 秒**。按實際成片時長計費，但不會超過請求時長 |
| `scenario` | string | 否 | 視頻類型：`auto` / `narrated` / `captions` / `avatar` / `drama`。`captions` 需傳源視頻，`avatar` 需傳人像 |
| `style` | string | 否 | 視覺風格預設：`auto`（默認）/ `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`，也接受自由文本作為軟提示。與 `scenario` 正交、不改變路由 |
| `voice` | string | 否 | 旁白音色（與語言無關，跨語言通用）：`auto`（默認）/ `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male` |

下面通過一個具體示例來演示。假設我們要生成一條中英雙語、豎屏、20 秒的科普短視頻，對應的 CURL 代碼如下：

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "用 20 秒講清楚什麼是向量數據庫，適合零基礎觀眾，結尾給一句記憶點",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'
```

對應的 Python 代碼如下：

```python theme={null}
import requests

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

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

payload = {
    "prompt": "用 20 秒講清楚什麼是向量數據庫，適合零基礎觀眾，結尾給一句記憶點",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

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

點擊運行，可以發現會立即得到一個結果，如下：

```json theme={null}
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}
```

返回結果的字段介紹如下：

* `success`：此次任務是否成功提交。
* `task_id`：此次視頻生成任務的 ID，後續用它去 [Maestro 任務查詢 API](/zh-Hant/guides/maestro/maestro_tasks) 輪詢結果。
* `trace_id`：本次請求的追蹤 ID，遇到問題時可提供給技術支持定位。

由於視頻生產耗時較長，接口在此**立即返回 `task_id`**，並不會等到視頻渲染完成。接下來需要用 `task_id` 去輪詢結果，詳見「取結果」一節。

## 指定視頻類型與風格（scenario / style）

不傳 `scenario` 時由 AI 自動判斷（等於 `auto`）；想把視頻釘到某種類型就顯式傳。例如做一條**豎屏短劇**，可以指定如下內容：

* `scenario`：視頻類型，這裡設為 `drama`（角色 + 對白的短劇）。
* `style`：視覺風格，這裡設為 `cinematic`（電影質感）。

填寫範例的 CURL 代碼如下：

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "兩個合租室友因為一隻貓鬧翻又和好，三幕反轉，結尾溫暖",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'
```

常見的搭配方式：

* 解說短片：`scenario: "narrated"`，Lite / Standard / Pro 均支持。
* 自動字幕：`scenario: "captions"`，需用 `file_urls` 傳源視頻，Lite / Standard / Pro 均支持。
* 數字人 / 口播：`scenario: "avatar"`，需用 `file_urls` 傳一張人像，Standard / Pro 支持。
* 短劇：`scenario: "drama"`（角色 + 對白），僅 Pro 支持。
* `style` 是視覺風格預設（如 `modern` / `neon` / `luxury`），不改變類型、只影響觀感。
* `voice` 用來指定旁白音色（如 `warm-female` / `deep-male`），與語言無關、跨語言通用。

返回結果與「基本使用」一致，同樣是立即返回 `task_id`。

## 多語言輸出

在 `langs` 中傳入多個語言即可一次產出多語言版本。第一個為主語言，之後每多一種語言會**複用同一套畫面**，只額外配音 + 渲染，因此**每多一種語言僅 +6 積分**。示例：

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "介紹我們的智能客服產品，突出 3 個核心賣點",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'
```

任務完成後，每種語言會對應結果裡的一個 `variant`（見 [Maestro 任務查詢 API](/zh-Hant/guides/maestro/maestro_tasks)）。

## 在已有視頻上迭代（remix / edit / extend）

傳入 `action` 與上一次任務的 `ref_task_id`，即可在原項目基礎上做差量修改（如「把第 2 幕標題改掉」「換個配音」「整體調暗」）。小改動很快、大改動會重做：

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "把開場標題換成更有衝擊力的一句，整體配色更暗一些"
}'
```

* `remix`：在原視頻結構上重新演繹（保留主題，調整表現）。
* `edit`：對指定局部做精修（如換標題、換配音、調色）。
* `extend`：在原視頻基礎上延展內容。

返回結果同樣是立即返回一個新的 `task_id`，用它輪詢即可拿到迭代後的成片。

## 取結果

由於視頻生產耗時較長，本接口在提交後立即返回 `task_id`，你需要用它去 [Maestro 任務查詢 API](/zh-Hant/guides/maestro/maestro_tasks) 輪詢結果：

```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"
}'
```

任務完成時會返回成片信息（每種語言對應一個 `variant`）。`status` 會經歷 `pending → planning → producing → succeeded`（或 `failed`），**輪詢免費、不消耗積分**。完整的響應格式與歷史列表查詢請參考 [Maestro 任務查詢 API 對接說明](/zh-Hant/guides/maestro/maestro_tasks)。

## 計費

**任務完成後按實際成片計費，失敗的任務不扣費。** 計費以實際交付的成片時長與語言數為準，且計費時長不會超過請求時長。某個語言最終沒有產出時，也不會收取該語言的 +6 加價。提交任務本身不單獨計費，`/maestro/tasks` 輪詢免費。

單個成片的積分按下式計算：

```
積分 = 成片時長秒 × 0.60 × 場景倍率 + 6 × max(語言數 − 1, 0)
```

Maestro 統一按 **0.60 積分/實際成片秒**計費，支持 5–300 秒、最多 4 種語言和 1080p / 30fps 輸出；所有動作與場景均可用。

場景倍率：`drama` 1.35× / `avatar` 1.15× / 其他 1×。

| 示例 | 積分 |
| - | -: |
| Lite 30 秒 | 6 |
| Standard 30 秒 | 18 |
| Standard 60 秒 | 36 |
| Standard 120 秒 | 72 |
| Pro 30 秒 | 36 |
| Pro 300 秒 | 360 |
| 每多一種實際交付語言 | +6 |
| `/maestro/tasks` 輪詢 | 免費 |

## 錯誤處理

在調用 API 時，如果遇到錯誤，API 會返回相應的錯誤代碼和信息。例如：

* `400 invalid_request`：Bad request, possibly due to a missing `prompt` or invalid parameters.
* `401 invalid_token`：Unauthorized, invalid or missing authorization token.
* `403 forbidden`：Forbidden, insufficient balance or access.
* `429 too_many_requests`：Too many requests, you have exceeded the rate limit.
* `500 api_error`：Internal server error, something went wrong on the server.

### 錯誤響應示例

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

## 結論

通過本文檔，您已經了解了如何使用 Maestro 視頻生成 API：只需一句自然語言 `prompt`，即可自動完成腳本、素材、配音、配樂、剪輯、字幕與成片渲染，並支持指定視頻類型、風格、音色、多語言輸出以及在已有視頻上迭代。希望本文檔能幫助您更好地對接和使用該 API。如有任何問題，請隨時聯繫我們的技術支持團隊。

## 相關接口

* [Maestro 任務查詢 API 對接說明](/zh-Hant/guides/maestro/maestro_tasks)：用 `POST /maestro/videos` 返回的 `task_id` 查詢任務狀態與結果，或拉取歷史任務列表（輪詢免費）。


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