跳转到主要内容
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: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。如有任何问题,请随时联系我们的技术支持团队。

相关接口