跳轉到主要內容
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"],預設為 ["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"。
  • 自動字幕:scenario: "captions",需用 file_urls 傳來源影片。
  • 數位人 / 口播:scenario: "avatar",需用 file_urls 傳一張人像。
  • 短劇:scenario: "drama"(角色 + 對白)。
  • style 是視覺風格預設(如 modern / neon / luxury),不改變類型、只影響觀感。
  • voice 用來指定旁白音色(如 warm-female / deep-male),與語言無關、跨語言通用。
返回結果與「基本使用」一致,同樣是立即返回 task_id。

成片語言

一個任務只交付一種語言的一支成片。langs 只能包含一個語言代碼,如 ["zh-cn"] 或 ["en"];傳入多個語言會返回 400。如果需要不同語言的影片,請分別建立任務。語言選擇不改變每秒價格。

在既有影片上迭代(remix / edit / extend)

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

取得結果

由於影片製作耗時較長,本介面在提交後立即返回 task_id,您需要用它去 Maestro 任務查詢 API 輪詢結果:
任務完成時會返回一條成片資訊(位於 variants 陣列)。status 會經歷 pending → planning → producing → succeeded(或 failed),輪詢免費、不消耗點數。完整的回應格式與歷史列表查詢請參考 Maestro 任務查詢 API 串接說明。

計費

任務成功後按實際交付的成片時長計費,失敗不扣費。 計費時長按整數秒統計,不超過請求時長;無法讀取成片時長時回退至請求時長。提交任務本身不另外計費,/maestro/tasks 輪詢免費。
所有場景、動作和語言採用相同價格,沒有場景倍率或語言加價。每個任務只交付一種語言的一支成片。請求目標時長支援 5–300 秒,統一輸出 1080p / 30fps。

錯誤處理

在呼叫 API 時,如果遇到錯誤,API 會返回相應的錯誤代碼和資訊。例如:
  • 400 invalid_request:錯誤的請求,可能是因為缺少 prompt 或參數無效。
  • 401 invalid_token:未授權,授權 Token 無效或缺失。
  • 403 forbidden:禁止存取,餘額或權限不足。
  • 429 too_many_requests:請求過多,您已超過速率限制。
  • 500 api_error:內部伺服器錯誤,伺服器發生異常。

錯誤回應範例

結論

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

相關介面