Maestro 视频生成 API 对接说明

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。

请求体的全部字段如下表所示：

字段	类型	必填	说明
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（画面比例提示，AI 可能依据 prompt 调整）
duration	int	否	目标时长（秒，1–600，即最长 10 分钟），默认 30。按实际成片时长计费，越长越贵（见下方计费）
quality	string	否	制作档位（作用在时长价格上的倍率）：draft（快速预览粗剪，约为标准档 0.5×）/ standard（默认，均衡，1×）/ premium（更精细、更出彩，耗时更久，约为标准档 2×）
scenario	string	否	视频类型路由提示（仅为提示，AI 导演仍决定最终结构）：auto（默认）/ narrated（多场景真实照片 + 旁白 + 数据卡）/ drama（角色 + 对白的短剧）/ avatar（数字人 / 口播，需用 file_urls 传人像）/ motion（抽象动感字幕 / 数据 / logo 动效）/ slideshow（演示 / 路演 deck）
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 代码如下：

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 代码如下：

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)

点击运行，可以发现会立即得到一个结果，如下：

{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}

返回结果的字段介绍如下：

• success：此次任务是否成功提交。
• task_id：此次视频生成任务的 ID，后续用它去 Maestro 任务查询 API 轮询结果。
• trace_id：本次请求的追踪 ID，遇到问题时可提供给技术支持定位。

由于视频生产耗时较长，接口在此立即返回 task_id，并不会等到视频渲染完成。接下来需要用 task_id 去轮询结果，详见「取结果」一节。

指定视频类型与风格（scenario / style）

不传 scenario 时由 AI 自动判断（等于 auto）；想把视频钉到某种类型就显式传。例如做一条竖屏短剧，可以指定如下内容：

• scenario：视频类型，这里设为 drama（角色 + 对白的短剧）。
• style：视觉风格，这里设为 cinematic（电影质感）。

填写样例的 CURL 代码如下：

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: "drama"（角色 + 对白）。
• 数字人 / 口播：scenario: "avatar"，并用 file_urls 传一张人像。
• 动感字幕 / 数据动画：scenario: "motion"；演示 / 路演：scenario: "slideshow"。
• style 是视觉风格预设（如 modern / neon / luxury），不改变类型、只影响观感。
• voice 用来指定旁白音色（如 warm-female / deep-male），与语言无关、跨语言通用。

返回结果与「基本使用」一致，同样是立即返回 task_id。

多语言输出

在 langs 中传入多个语言即可一次产出多语言版本。第一个为主语言，之后每多一种语言会复用同一套画面，只额外配音 + 渲染，因此每多一种语言仅 +6 积分。示例：

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）。

在已有视频上迭代（remix / edit / extend）

传入 action 与上一次任务的 ref_task_id，即可在原项目基础上做差量修改（如「把第 2 幕标题改掉」「换个配音」「整体调暗」）。小改动很快、大改动会重做：

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 轮询结果：

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 对接说明。

计费

任务完成后按实际成片计费，失败的任务不扣费。 计费以实际交付的成片时长与实际产出的语言数为准——例如请求 600 秒但最终成片 50 秒，只按约 50 秒计费；某个语言最终没有产出时，也不会收取该语言的 +6 加价。提交任务本身不单独计费（结果由 /maestro/tasks 免费轮询）。

单个成片的积分大致按下式估算：

积分 ≈ 0.85 × 成片时长秒 × 质量倍率 × 场景倍率 + 6 × max(语言数 − 1, 0)

• 质量倍率：draft 0.5× / standard 1×（默认）/ premium 2×。
• 场景倍率：drama 1.35× / avatar 1.15× / 其他 1×。

以标准档、非短剧 / 数字人、单语言为例，不同成片时长对应的积分约为：

成片时长	标准档积分
30s	25.5
60s	51
120s（2 分钟）	102
300s（5 分钟）	255
600s（10 分钟，上限）	510
每多一种语言（langs 超过 1 种，每多一种）	+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.

错误响应示例

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

结论

通过本文档，您已经了解了如何使用 Maestro 视频生成 API：只需一句自然语言 prompt，即可自动完成脚本、素材、配音、配乐、剪辑、字幕与成片渲染，并支持指定视频类型、风格、音色、多语言输出以及在已有视频上迭代。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

相关接口

• Maestro 任务查询 API 对接说明：用 POST /maestro/videos 返回的 task_id 查询任务状态与结果，或拉取历史任务列表（轮询免费）。