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。如有任何问题，请随时联系我们的技术支持团队。

​
相关接口