Skip to main content
Maestro 是一個 Agent 原生 的視頻生產接口：你用一句自然語言 prompt 描述想要的視頻（可選地用 file_urls 附上參考圖片 / 視頻 / 音頻），一個無頭的「AI 導演」會自動完成選題、寫腳本、生成畫面、配音、配樂、合成與渲染，最終產出帶字幕的成片並上傳 CDN。 本文將詳細介紹 Maestro 視頻生成 API 的對接說明，幫助您快速集成並充分利用該 API 的能力。 這是一個異步任務接口：提交後會立即返回 task_id，隨後通過 Maestro 任務查詢 API（POST /maestro/tasks）輪詢獲取結果（輪詢免費不計費）。要在已有視頻上繼續迭代，可使用 action: remix / edit / extend 配合 ref_task_id。

​
申請流程

要使用 Maestro 視頻生成 API，首先到 Ace Data Cloud 控制台 獲取您的 API Token，留作備用。 如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。 一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在 控制台 充值通用餘額。
📘 完整文檔：Maestro 視頻生成 API →

​
基本使用

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。
請求體的全部字段如下表所示： 下面通過一個具體示例來演示。假設我們要生成一條中英雙語、豎屏、20 秒的科普短視頻，對應的 CURL 代碼如下：
對應的 Python 代碼如下：
點擊運行，可以發現會立即得到一個結果，如下：
返回結果的字段介紹如下：
  • success：此次任務是否成功提交。
  • task_id：此次視頻生成任務的 ID，後續用它去 Maestro 任務查詢 API 輪詢結果。
  • trace_id：本次請求的追蹤 ID，遇到問題時可提供給技術支持定位。
由於視頻生產耗時較長，接口在此立即返回 task_id，並不會等到視頻渲染完成。接下來需要用 task_id 去輪詢結果，詳見「取結果」一節。

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

不傳 scenario 時由 AI 自動判斷（等於 auto）；想把視頻釘到某種類型就顯式傳。例如做一條豎屏短劇，可以指定如下內容：
  • scenario：視頻類型，這裡設為 drama（角色 + 對白的短劇）。
  • style：視覺風格，這裡設為 cinematic（電影質感）。
填寫範例的 CURL 代碼如下：
常見的搭配方式：
  • 解說短片：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 積分。示例：
任務完成後，每種語言會對應結果裡的一個 variant（見 Maestro 任務查詢 API）。

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

傳入 action 與上一次任務的 ref_task_id，即可在原項目基礎上做差量修改（如「把第 2 幕標題改掉」「換個配音」「整體調暗」）。小改動很快、大改動會重做：
  • remix：在原視頻結構上重新演繹（保留主題，調整表現）。
  • edit：對指定局部做精修（如換標題、換配音、調色）。
  • extend：在原視頻基礎上延展內容。
返回結果同樣是立即返回一個新的 task_id，用它輪詢即可拿到迭代後的成片。

​
取結果

由於視頻生產耗時較長，本接口在提交後立即返回 task_id，你需要用它去 Maestro 任務查詢 API 輪詢結果：
任務完成時會返回成片信息（每種語言對應一個 variant）。status 會經歷 pending → planning → producing → succeeded（或 failed），輪詢免費、不消耗積分。完整的響應格式與歷史列表查詢請參考 Maestro 任務查詢 API 對接說明。

​
計費

任務完成後按實際成片計費，失敗的任務不扣費。 計費以實際交付的成片時長與語言數為準，且計費時長不會超過請求時長。某個語言最終沒有產出時，也不會收取該語言的 +6 加價。提交任務本身不單獨計費，/maestro/tasks 輪詢免費。 單個成片的積分按下式計算：
Maestro 統一按 0.60 積分/實際成片秒計費，支持 5–300 秒、最多 4 種語言和 1080p / 30fps 輸出；所有動作與場景均可用。 場景倍率：drama 1.35× / avatar 1.15× / 其他 1×。

​
錯誤處理

在調用 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.

​
錯誤響應示例

​
結論

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

​
相關接口