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:Bad request, possibly due to a missingpromptor 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。如有任何问题,请随时联系我们的技术支持团队。
相关接口
- Maestro 任务查询 API 对接说明:用
POST /maestro/videos返回的task_id查询任务状态与结果,或拉取历史任务列表(轮询免费)。

