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。
prompt:使用自然語言描述要製作的影片(主題、要呈現的內容、風格、受眾)。langs:成片語言陣列,每次僅傳入一種,例如["zh-cn"],預設為["zh-cn"]。aspect:畫面比例,9:16(預設)/16:9/1:1。duration:目標時長(秒),預設為 30。
以下透過一個具體範例來示範。假設我們要生成一支中文、直式、20 秒的科普短影片,對應的 cURL 程式碼如下:
success:此次任務是否成功提交。task_id:此次影片生成任務的 ID,後續可使用它透過 Maestro 任務查詢 API 輪詢結果。trace_id:本次請求的追蹤 ID,遇到問題時可提供給技術支援人員進行定位。
task_id,不會等待影片渲染完成。接下來需要使用 task_id 輪詢結果,詳見「取得結果」一節。
指定影片類型與風格(scenario / style)
不傳scenario 時由 AI 自動判斷(等於 auto);想把影片固定為某種類型就明確傳入。例如製作一支直式短劇,可以指定如下內容:
scenario:影片類型,這裡設為drama(角色 + 對白的短劇)。style:視覺風格,這裡設為cinematic(電影質感)。
- 解說短片:
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 輪詢免費。
錯誤處理
在呼叫 API 時,如果遇到錯誤,API 會返回相應的錯誤代碼和資訊。例如:400 invalid_request:錯誤的請求,可能是因為缺少prompt或參數無效。401 invalid_token:未授權,授權 Token 無效或缺失。403 forbidden:禁止存取,餘額或權限不足。429 too_many_requests:請求過多,您已超過速率限制。500 api_error:內部伺服器錯誤,伺服器發生異常。
錯誤回應範例
結論
透過本文檔,您已經瞭解如何使用 Maestro 影片生成 API:只需一句自然語言prompt,即可自動完成腳本、素材、配音、配樂、剪輯、字幕與成片渲染,並支援指定影片類型、風格、音色、成片語言以及在既有影片上迭代。希望本文檔能幫助您更好地串接和使用該 API。如有任何問題,請隨時聯絡我們的技術支援團隊。
相關介面
- Maestro 任務查詢 API 串接說明:用
POST /maestro/videos返回的task_id查詢任務狀態與結果,或取得歷史任務列表(輪詢免費)。

