视频时间线渲染

将一份通用的时间线结构直接渲染为成片视频（mp4）。与工程文件生成共用同一时间线数据模型：同一份时间线，一边可导出剪辑工程继续精修，一边可直接云端出片。

与工程文件生成的关键差异：渲染需要真实读取素材，因此 material_map 必须提供 file_id（{素材ID: 平台文件ID}），素材需先上传到平台；material_map.path 在本接口中被忽略。

创建任务

基本信息

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

请求参数（Body）

参数名	类型	必填	默认值	说明
`video_size`	`array`	是	—	输出分辨率 `[宽, 高]`（像素），如 `[1920, 1080]`
`video_rate`	`number`	是	—	输出帧率（fps），如 `30`
`video_track`	`array`	是	—	视频轨列表，当前版本仅支持恰好 1 条
`audio_track`	`array`	是	—	音频轨列表，0 ~ N 条（多轨自动混音；空数组 `[]` = 全程静音）
`material_map`	`object`	是	—	素材映射，必须含 `file_id`，详见下表
`render`	`object`	否	`{}`	渲染参数，详见下表

track_timeline[] 中的片段对象

字段	类型	必填	说明
`clip_id`	`string`	是	素材 ID（对应 `material_map.file_id` 的键）；空串 `""` 表示空档（视频轨=黑场，音频轨=静音）
`clip_st`	`number`	是	取用素材内的起始时间（秒）
`track_st`	`number`	是	片段在成片时间轴上的起始时间（秒），同轨内不得重叠
`duration`	`number`	是	片段时长（秒），必须 > 0

兼容说明：与工程文件生成共用的时间线中可能还带 clip_ed / track_ed 等冗余字段，本接口会忽略它们，只读上表四个字段。轨道时间轴上的不连续区段自动按空档（黑场/静音）填充。

material_map 字段

字段	类型	必填	说明
`file_id`	`object`	是	`{素材ID: 平台文件ID}`；视频轨素材须为视频文件，音频轨素材可为音频或视频文件
其余字段（`path` / `duration` / `video_rate` / `video_size`）	—	否	渲染时忽略，可与工程文件生成共用同一份时间线原样传入

render 对象

字段	类型	默认值	说明
`codec`	`string`	`h264`	视频编码器，当前仅支持 `h264`
`crf`	`integer`	`18`	画质参数，14（高质量）~ 28（小体积）
`audio_crossfade_ms`	`integer`	`8`	每个音频片段首尾淡化毫秒数（0 ~ 50），消除拼接爆音；`0` 为硬切

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/video_timeline_render \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_size": [1280, 720],
    "video_rate": 30,
    "video_track": [
      {"track_timeline": [
        {"clip_id": "src", "clip_st": 18.50, "track_st": 0.0, "duration": 9.55},
        {"clip_id": "", "clip_st": 0, "track_st": 9.55, "duration": 1.0},
        {"clip_id": "src", "clip_st": 33.70, "track_st": 10.55, "duration": 11.92}
      ]}
    ],
    "audio_track": [
      {"track_timeline": [
        {"clip_id": "src", "clip_st": 18.50, "track_st": 0.0, "duration": 9.55},
        {"clip_id": "src", "clip_st": 33.70, "track_st": 10.55, "duration": 11.92}
      ]}
    ],
    "material_map": {"file_id": {"src": "78246108192718854"}},
    "render": {"crf": 18, "audio_crossfade_ms": 8}
  }'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178400",
    "task_type": "video_timeline_render",
    "status": "queued"
  }
}

查询任务结果

基本信息

项目	值
请求方法	`GET`
请求路径	`/task/video_timeline_render/{task_id}`
鉴权方式	`Authorization` 请求头（直接传 API Key）

响应参数（output_result）

参数名	类型	说明
`file_id`	`string`	成片文件 ID
`download_url`	`string`	下载路径
`duration`	`number`	成片时长（秒），等于时间线总时长
`video_size`	`array`	输出分辨率 `[宽, 高]`

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178400",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "file_id": "537489015178401",
      "download_url": "/download/c1/537489015178401.mp4",
      "duration": 22.47,
      "video_size": [1280, 720]
    },
    "create_time": "2026-06-11T08:00:00Z",
    "update_time": "2026-06-11T08:00:25Z"
  }
}

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	必填参数缺失（`video_size` / `video_rate` / `video_track` / `audio_track` / `material_map`）	补齐必填参数
`6016`	400	结构非法（视频轨数 ≠ 1、clip 总数超上限、时长 ≤ 0、`render` 参数越界、缺 `material_map.file_id` 等，响应中附具体原因）	按响应提示修正时间线
`6004`	404	`material_map.file_id` 中某个文件不存在	检查文件 ID 是否正确、是否已上传
`6014`	400	素材类型与轨道不匹配（视频轨引用了非视频文件等）	检查素材类型
`6502`	401	鉴权失败	检查 `Authorization` 请求头
`6201`	402	配额不足	购买配额包或充值
`6202`	402	余额不足	前往仪表盘充值

使用限制

单视频轨：当前版本仅支持 1 条视频轨（多轨画中画 / 叠加合成暂不支持）；音频轨可多条，自动混音。
片段数上限：全部轨道 clip 总数 ≤ 500。
必然重编码：切点通常不在关键帧上，渲染会重新编码（h264 + aac），耗时与成片时长成正比，建议每 5 ~ 10 秒轮询一次。
素材自动归一：不同分辨率 / 帧率的素材会自动缩放、加黑边适配到 video_size 并统一帧率，可放心混用异构素材。
按成片时长计费：以时间线总时长（分钟）计费，与素材原始长度无关。
与工程文件生成互补：同一份时间线（带 file_id 的 material_map）可同时调用两个接口——一边拿工程进剪辑软件精修，一边云端直接出片。