Maestro 视频生成 API 对接说明
内容提要
Maestro 视频生成 API 支持通过自然语言 prompt 自动生成带字幕的视频，可指定场景、风格、音色、多语言，并支持在已有视频上迭代。提交后返回 task_id，需轮询查询结果。计费基于实际成片时长、语言数和质量档位，失败任务不扣费。
延伸解读
异步任务与轮询机制
Maestro 视频生成 API 采用异步任务模式，提交后立即返回 task_id，实际视频生成耗时较长，需通过任务查询接口轮询获取结果。轮询免费且不消耗积分，但需注意轮询频率，避免触发限流（429 错误）。建议根据任务状态（pending → planning → producing → succeeded/failed）合理设置轮询间隔，以平衡实时性与资源消耗。
计费细节与成本控制
计费基于实际成片时长、语言数和质量档位，而非请求参数。例如请求 600 秒但成片仅 50 秒，只按 50 秒计费；未产出的语言不收取额外费用。质量档位（draft/standard/premium）和场景倍率（drama/avatar）会影响单价，多语言每增加一种加 6 积分。失败任务不扣费，但需注意提交任务本身不收费，仅成片计费。
迭代操作与使用场景
支持 remix、edit、extend 三种迭代操作，需配合 ref_task_id 使用。remix 保留主题重新演绎，edit 精修局部，extend 延展内容。适合需要快速调整视频的场景，如修改标题、换配音或调色。小改动响应快，大改动可能重做，建议明确 prompt 描述修改意图，以提高迭代效率。
Q&A
Maestro 视频生成 API 是什么？
Maestro 是一个 Agent 原生的视频生产接口，用户只需用自然语言 prompt 描述想要的视频，AI 导演会自动完成选题、写脚本、生成画面、配音、配乐、合成与渲染，最终产出带字幕的成片并上传 CDN。
如何申请 Maestro 视频生成 API 的访问权限？
首先到 Ace Data Cloud 控制台获取 API Token，如果未登录或注册会自动跳转。一个 API Token 即可调用平台所有服务，首次申请会赠送免费额度，额度不足时可在控制台充值通用余额。
Maestro 视频生成 API 的请求参数有哪些？
主要参数包括：prompt（必填，自然语言描述）、action（generate/remix/edit/extend）、ref_task_id（迭代时必填）、file_urls（参考媒体）、langs（输出语言，默认zh-cn）、aspect（画面比例，默认9:16）、duration（目标时长，默认30秒）、quality（制作档位，默认standard）、scenario（视频类型，默认auto）、style（视觉风格，默认auto）、voice（旁白音色，默认auto）。
如何指定视频类型和风格？
通过 scenario 参数指定视频类型，如 drama（短剧）、avatar（数字人）、motion（动感字幕）、slideshow（演示）；通过 style 参数指定视觉风格，如 cinematic、modern、neon 等。不传时由 AI 自动判断。
如何生成多语言视频？
在请求的 langs 参数中传入多个语言代码，如 ["zh-cn", "en", "ja"]，第一个为主语言，每多一种语言会复用画面，只额外配音和渲染，每多一种语言加 6 积分。任务完成后每种语言对应一个 variant。
如何在已有视频上进行迭代修改？
使用 action 参数（remix/edit/extend）并传入 ref_task_id（历史任务的 task_id）。remix 是在原视频结构上重新演绎，edit 是对局部精修，extend 是延展内容。提交后返回新的 task_id，用其轮询结果。
如何获取视频生成任务的结果？
提交任务后立即返回 task_id，然后使用 Maestro 任务查询 API（POST /maestro/tasks）轮询结果，传入 task_id。任务状态会经历 pending → planning → producing → succeeded（或 failed），轮询免费不消耗积分。
Maestro 视频生成 API 如何计费？
按实际成片时长、语言数和质量档位计费，失败任务不扣费。积分估算公式：1 积分 ≈ 0.85 × 成片时长秒 × 质量倍率 × 场景倍率 + 6 × max(语言数−1, 0)。质量倍率：draft 0.5×，standard 1×，premium 2×；场景倍率：drama 1.35×，avatar 1.15×，其他 1×。轮询免费。
调用 Maestro 视频生成 API 可能遇到哪些错误？
常见错误包括：400 invalid_request（请求参数缺失或无效）、401 invalid_token（授权令牌无效）、403 forbidden（余额不足或权限不足）、429 too_many_requests（请求频率超限）、500 api_error（服务器内部错误）。
