HTML 动画渲染（单点）

将一份合成规格渲染为成片视频（mp4）：把视频底轨 + 自定义 HTML 动画颗粒一次合成出片。面向不透明全屏颗粒切入 / 短片段 / 纯 HTML 动画等场景（无长视频底轨贯穿，或颗粒全屏盖住底轨）——更轻、更快。视觉玩法不预设、不枚举，颗粒由你自由编写，只需遵守渲染所需的 HTML 动画格式。素材通过 composition.assets.file_id 引用平台已有文件。

选哪个接口？

本接口 · 单点：颗粒不透明全屏切入 / 短片段 / 纯 HTML 动画（无长底轨贯穿）→ 用本接口，更轻更快。

HTML 动画渲染（整轨）：有一条长视频底轨贯穿全片（人物出镜 / B-roll），透明颗粒叠在其上、不挡主体 → 用整轨接口。

两个接口输入规格完全相同（composition v0），按你的画面场景择一即可。

颗粒格式约定（重要）

每个自定义 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_render_simple`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头（直接传 API Key）
计费	按成片总时长（分钟）计费

请求参数（Body）

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

render 对象

字段	类型	必填	默认值	说明
`fps`	`number`	否	`composition.fps` 或 30	渲染帧率
`quality`	`string`	否	`high`	`draft` / `standard` / `high`
`output_format`	`string`	否	`mp4`	输出模式（详见下方说明）：`mp4` = 底轨 + 颗粒不透明单点合成 → `.mp4`；`webm` = 只渲透明颗粒层（beats-only）为 VP8-alpha WebM → `.webm`；`qtrle` = 只渲透明颗粒层（beats-only）为 QuickTime Animation（qtrle, argb）alpha MOV → `.mov`

output_format 输出模式

mp4（默认）：底轨 + 颗粒不透明单点合成为一条成片（.mp4），即现状行为。
webm：只渲透明颗粒层（beats-only）为 VP8-alpha WebM（.webm）。底轨不参与合成（留在本地），该 WebM 供客户端浏览器经 WebCodecs / mediabunny 解码、在客户端本地原生合成叠到本地底轨之上。
qtrle：只渲透明颗粒层（beats-only）为 QuickTime Animation（qtrle, argb）alpha MOV（.mov），供导入剪映做透明叠加素材（剪映只稳吃 qtrle；webm / ProRes-alpha 在剪映里是黑底）。
透明层模式（webm / qtrle）语义：composition.tracks 可为空（mp4 仍要求至少 1 条；webm / qtrle 放宽此限制）；底轨不写入输出，输出时长 = beats 末端。

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`），`mp4` 下至少 1 条；透明层模式下（`render.output_format` = `webm` / `qtrle`）可为空，底轨不进输出
`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`	否	颗粒是否全屏不透明（盖住底轨）。单点场景常为 `true`（全屏切入）；纯 HTML 动画亦可透明
`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_render_simple \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "composition": {
      "version": "v0",
      "video_size": {"width": 1920, "height": 1080},
      "fps": 30,
      "duration": 5.0,
      "assets": {"file_id": {"base": "78246108192718854"}},
      "tracks": [
        {"type": "video", "asset": "base", "track_index": 0, "start": 0, "duration": 5.0, "muted": true}
      ],
      "beats": [
        {"id": "b1", "start": 0.5, "duration": 4.0, "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_render_simple", "status": "queued"}}

查询任务结果

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

响应参数（output_result）

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

产物随 render.output_format 而定：mp4 → 合成好的成片（.mp4）；webm / qtrle → 只含透明颗粒层（.webm / .mov），供客户端在本地底轨上原生合成 / 导入剪映叠加，非合成 mp4。

错误码

错误码	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。
输出格式：render.output_format 取值须为 mp4 / webm / qtrle 之一（默认 mp4），其余值按 render 参数越界拒绝。透明层模式（webm / qtrle）下底轨不进输出，composition.tracks 可为空，产物为 beats-only 透明颗粒层（.webm / .mov）。
颗粒须可 seek：颗粒须用 <template> 包裹根元素 + 自带 data-composition-id + 可逐帧驱动的时间线注册（见上「颗粒格式约定」）；纯 CSS 无注册的颗粒会冻结。
片段数上限：视频底轨 + 颗粒总数 ≤ 200。
按成片时长计费：以成片总时长（分钟）计费；含逐帧渲染，耗时与时长/复杂度相关，建议每 5 ~ 10 秒轮询一次。
适用场景：本接口面向不透明全屏切入 / 短片段 / 纯 HTML 动画；若是长视频底轨贯穿 + 透明颗粒叠加（人物出镜 + 图形叠加不挡主体），请用 HTML 动画渲染（整轨）。
与时间线渲染互补：单轨快速硬切用视频时间线渲染；视频底轨 + 自定义动画颗粒用本接口。