HTML 动画渲染（整轨）

将一份合成规格渲染为成片视频（mp4）：以一条贯穿全片的视频底轨（如真人出镜 A-roll）为底，叠加任意自定义 HTML 动画颗粒（透明叠在底轨之上、不挡主体），一次合成出片。视觉玩法不预设、不枚举——颗粒由你自由编写，只需遵守渲染所需的 HTML 动画格式。素材通过 composition.assets.file_id 引用平台已有文件。

选哪个接口？

• 本接口 · 整轨：有一条长视频底轨贯穿全片（人物出镜 / B-roll），透明颗粒叠在其上、不挡主体 → 用本接口。
• HTML 动画渲染（单点）：颗粒不透明全屏切入 / 短片段 / 纯 HTML 动画（无长底轨贯穿）→ 用单点接口，更轻更快。
• 两个接口输入规格完全相同（composition v0），按你的画面场景择一即可。

与 视频时间线渲染 的差异：时间线渲染是单视频轨硬切；本接口支持视频底轨 + 多个自定义 HTML 动画颗粒叠加合成，视觉表现完全由你的颗粒决定。

颗粒格式约定（重要）

每个自定义 HTML 颗粒必须是自包含、可逐帧定格（seekable）的 HTML 动画：

• 根元素必须用 <template> 包裹：<template><div data-composition-id=...>…</div></template>，否则颗粒无法被解析、整体渲染会失败；
• 必须声明自己的 data-composition-id / data-width / data-height；
• 动画必须注册到可被逐帧驱动的时间线（推荐 GSAP：gsap.timeline({paused:true}) 注册到 window.__timelines）。
• ⚠️ 仅用纯 CSS animation-delay、不注册时间线的颗粒无法被逐帧渲染，会冻结在动画终态。 请按可 seek 的动画格式产出颗粒。

创建任务

基本信息

项目	值
请求方法	POST
请求路径	/task/html_animate_render
Content-Type	application/json
鉴权方式	Authorization 请求头（直接传 API Key）
计费	按成片总时长（分钟）计费

请求参数（Body）

参数名	类型	必填	默认值	说明
composition	object	是	—	合成规格，详见下表
render	object	否	{}	渲染参数：fps（默认取 composition.fps 或 30）/ quality（draft/standard/high，默认 high）

composition 对象

字段	类型	必填	默认值	说明
version	string	是	—	规格版本，固定 v0
video_size	object	是	—	输出分辨率 {"width":宽,"height":高}
fps	number	否	30	输出帧率
duration	number	否	自动	成片总时长（秒）；缺省时取所有轨道 / 颗粒末端最大值
assets	object	是	—	素材引用，必须含 file_id：{素材名: 平台文件ID}（含视频/音频底轨，以及以 file_id 方式引用的颗粒文件）
tracks	array	是	—	视频底轨（video/audio），至少 1 条
beats	array	否	[]	自定义 HTML 动画颗粒叠加层

tracks[] 视频底轨对象

字段	类型	必填	说明
type	string	是	video 或 audio
asset	string	是	素材名（对应 assets.file_id 的键）
track_index	number	是	轨道层级（越大越靠前；同层不可重叠）
start	number	是	在成片时间轴上的起始时间（秒）
duration	number	否	时长（秒）；视频/音频可省略（取源时长）
muted	boolean	否	视频专用，默认 true（音频建议走独立音频轨）
volume	number	否	音频专用，默认 1.0

beats[] 颗粒叠加层对象

字段	类型	必填	说明
id	string	否	唯一标识
start	number	是	入场时间（秒）
duration	number	是	在场时长（秒）
track_index	number	是	叠加层级（z-order）
opaque	boolean	否	颗粒是否全屏不透明（盖住底轨）。整轨场景通常为 false（透明叠在底轨上、不挡主体）；若颗粒需全屏盖住底轨切入，置 true
html	string	二选一	内联：直接把颗粒 HTML 源码塞进字段（自包含、一次调用）
html_asset	string	二选一	引用：颗粒 HTML 已上传，填其在 assets.file_id 中的键

每个颗粒须提供 html（内联）或 html_asset（file_id 引用）其一。

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/html_animate_render \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "composition": {
      "version": "v0",
      "video_size": {"width": 1920, "height": 1080},
      "fps": 30,
      "duration": 8.5,
      "assets": {"file_id": {"base": "78246108192718854", "base_audio": "78246108192718855"}},
      "tracks": [
        {"type": "video", "asset": "base",       "track_index": 0, "start": 0, "duration": 8.5, "muted": true},
        {"type": "audio", "asset": "base_audio", "track_index": 5, "start": 0, "duration": 8.5, "volume": 1.0}
      ],
      "beats": [
        {"id": "b1", "start": 3.0, "duration": 4.6, "track_index": 10, "opaque": true,
         "html": "<template><div data-composition-id=\"p1\" data-width=\"1920\" data-height=\"1080\">...含 GSAP 时间线注册的颗粒 HTML...</div></template>"}
      ]
    },
    "render": {"fps": 30, "quality": "high"}
  }'

成功响应示例

{"code": 200, "msg": "success", "data": {"task_id": "537489015178500", "task_type": "html_animate_render", "status": "queued"}}

---

查询任务结果

项目	值
请求方法	GET
请求路径	/task/html_animate_render/{task_id}
鉴权方式	Authorization 请求头

响应参数（output_result）

参数名	类型	说明
file_id	string	成片文件 ID
download_url	string	下载路径
duration	number	成片时长（秒）
video_size	object	输出分辨率 {"width":宽,"height":高}

错误码

错误码	HTTP 状态码	说明	解决方案
6013	400	缺少 composition	补齐必填参数
6016	400	规格非法（version ≠ v0、颗粒缺 html/html_asset、clip 总数超上限、总时长 ≤ 0、render 参数越界等）	按响应提示修正
6004	404	assets.file_id 中某个文件不存在	检查文件 ID / 是否已上传
6014	400	底轨素材类型与轨道不匹配	检查素材类型
6502	401	鉴权失败	检查 Authorization 请求头
6201 / 6202	402	配额 / 余额不足	购买配额包或充值

使用限制

• 规格版本：composition.version 必须为 v0。
• 颗粒须可 seek：颗粒须用 <template> 包裹根元素 + 自带 data-composition-id + 可逐帧驱动的时间线注册（见上「颗粒格式约定」）；纯 CSS 无注册的颗粒会冻结。
• 片段数上限：视频底轨 + 颗粒总数 ≤ 200。
• 按成片时长计费：以成片总时长（分钟）计费；含逐帧渲染，耗时与时长/复杂度相关，建议每 5 ~ 10 秒轮询一次。
• 适用场景：本接口面向长视频底轨贯穿 + 透明颗粒叠加（人物出镜 + 图形叠加不挡主体）；若是不透明全屏切入 / 短片段 / 纯 HTML 动画，请用更轻快的 HTML 动画渲染（单点）。
• 与时间线渲染互补：单轨快速硬切用 视频时间线渲染；视频底轨 + 自定义动画颗粒用本接口。