视频时间线渲染
将一份 gtrk v1 时间线结构 直接渲染为成片视频（单个 mp4）。与 工程文件生成 共用同一份 gtrk v1 契约：同一份时间线，一边可导出剪辑工程继续精修，一边可直接云端出片。
ℹ️ 说明：与工程文件生成不同，渲染需要真实读取素材，因此
materials[].id必须是已上传到平台的文件 ID（file_id）；materials[].path（本地路径）在本接口中被忽略。被片段引用的每条素材都须先上传。
创建任务
基本信息
| 项目 | 值 |
|---|---|
| 请求方法 | POST |
| 请求路径 | /task/video_timeline_render |
| Content-Type | application/json |
| 鉴权方式 | Authorization 请求头（直接传 API Key） |
| 计费 | 按输入时长（成片总时长，分钟）计费 |
请求参数（Body）
请求体即一份 gtrk v1 时间线结构。所有时间字段单位均为秒。
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
version | string | 是 | — | 契约版本，固定为 "v1" |
video_size | array | 是 | — | 输出画布尺寸 [宽, 高]（像素），如 [1920, 1080] |
video_rate | number | 是 | — | 输出帧率（fps，整数），如 30 |
duration | number | 否 | 自动 | 成片总时长（秒）；缺省时按时间线末端自动推得 |
materials | array | 是 | — | 素材清单（列表），每条 id 即平台文件 ID，详见下表 |
video_track | array | 是 | — | 视频轨列表。本接口仅渲染 1 条视频轨，详见下表与「使用限制」 |
audio_track | array | 是 | — | 音频轨列表（分层），0 ~ N 条；多轨自动混音，空数组 [] = 全程静音 |
beat_track | array | 否 | [] | HTML 颗粒叠加层。本接口忽略 beat_track，要渲染颗粒请走 html_animate_render |
struct_meta | object | 否 | {} | 草稿落盘等元信息；本接口忽略，可与工程文件生成共用同一份时间线原样传入 |
materials[] 素材条目
每条素材以单一 id 标识——本接口中 id 即平台文件 ID（file_id），素材须先上传。片段以 material 字段引用此 id。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 是 | 素材唯一标识，即平台文件 ID（file_id），被片段以 material 引用 |
path | string | 否 | 本地素材路径；本接口忽略（仅供工程文件生成 / 离线 ffmpeg 使用） |
duration | number | 否 | 素材总时长（秒） |
video_size | array | 否 | 素材原始尺寸 [宽, 高]（视频素材） |
video_rate | number | 否 | 素材帧率（视频素材） |
audio_channel | string | 否 | 声道，取 "stereo" 或 "mono"（音频素材） |
💡 提示：视频轨引用的素材须为视频文件，音频轨引用的素材可为音频或视频文件。
materials[].path/duration/video_size/video_rate/audio_channel在渲染时仅作参考，可与工程文件生成共用同一份时间线原样传入。
video_track[] 视频轨对象
track_index 是显式 z 层级整数，track_index 最小那条即底轨（main）。本接口只渲染 main 底轨这一条视频轨——多出的 overlay 视频轨会被忽略（见「使用限制」）。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
track_index | number | 是 | 显式层级；最小者为底轨（main），即本接口实际渲染的那条 |
track_size | array | 否 | 本轨素材原始尺寸 [宽, 高]，供按画布 video_size 缩放适配 |
muted | boolean | 否 | 轨级默认静音态，可被 clip 级 muted 覆盖 |
track_timeline | array | 是 | 轨道上的片段序列，元素为片段对象 |
audio_track[] 音频轨对象
音频轨可多条，自动混音。volume 为轨级与 clip 级双层语义。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
track_index | number | 是 | 显式层级（多条音频轨用以区分） |
volume | number | 否 | 轨级默认音量，可被 clip 级 volume 覆盖；缺省 1.0 |
track_timeline | array | 是 | 轨道上的片段序列，元素为片段对象 |
track_timeline[] 片段对象（video / audio）
每个非空档片段同时携带源裁剪时码（clip_st/clip_ed）与轨上时码（track_st/track_ed/duration），两套时码冗余保留。本接口据此从源素材 clip_st~clip_ed 取片，落到成片 track_st 处。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
clip_id | string | 是 | 片段标识；空串 "" 表示空档（Gap）（视频轨=黑场，音频轨=静音），空档不写 material / clip_st / clip_ed |
material | string | 是 | 引用 materials[].id（空档不写） |
clip_st | number | 是 | 源素材内的裁剪入点（秒） |
clip_ed | number | 是 | 源素材内的裁剪出点（秒） |
track_st | number | 是 | 片段在成片时间轴上的入点（秒），同轨内不得重叠 |
track_ed | number | 是 | 片段在成片时间轴上的出点（秒） |
duration | number | 是 | 片段时长（秒），必须 > 0 |
muted | boolean | 否 | （video）clip 级静音，覆盖轨级 muted |
volume | number | 否 | （audio）clip 级音量，覆盖轨级 volume |
ℹ️ 静音 / 音量双层语义：视频用
muted、音频用volume，轨级与 clip 级各一层。优先级为：clip 级有则用 clip 级，否则用轨级，两级都无则缺省（muted缺省false、volume缺省1.0）。
请求示例
下例演示一个源剪多段 + 一条音轨：materials 声明一条视频源（F100）与一条背景音乐（F200），video_track 用同一视频源的不同 clip_st/clip_ed 切出多段拼接（中间留一段黑场空档），audio_track 铺一条 BGM。
curl -X POST https://api.ai-mcn.tv:10000/task/video_timeline_render \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"version": "v1",
"video_size": [1280, 720],
"video_rate": 30,
"duration": 22.47,
"materials": [
{
"id": "F100",
"duration": 120.0,
"video_size": [1920, 1080],
"video_rate": 30,
"audio_channel": "stereo"
},
{
"id": "F200",
"duration": 180.0,
"audio_channel": "stereo"
}
],
"video_track": [
{
"track_index": 0,
"track_size": [1920, 1080],
"muted": false,
"track_timeline": [
{
"clip_id": "c1", "material": "F100",
"clip_st": 18.50, "clip_ed": 28.05,
"track_st": 0.0, "track_ed": 9.55, "duration": 9.55
},
{
"clip_id": "",
"track_st": 9.55, "track_ed": 10.55, "duration": 1.0
},
{
"clip_id": "c2", "material": "F100",
"clip_st": 33.70, "clip_ed": 45.62,
"track_st": 10.55, "track_ed": 22.47, "duration": 11.92
}
]
}
],
"audio_track": [
{
"track_index": 0,
"volume": 0.8,
"track_timeline": [
{
"clip_id": "a1", "material": "F200",
"clip_st": 0.0, "clip_ed": 22.47,
"track_st": 0.0, "track_ed": 22.47, "duration": 22.47
}
]
}
]
}'
成功响应示例
{
"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）
产物是单个 mp4 成片。
| 参数名 | 类型 | 说明 |
|---|---|---|
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 | 必填参数缺失（version / video_size / video_rate / materials / video_track / audio_track） | 补齐必填参数 |
6016 | 400 | 结构非法（material 不在 materials 列表中、clip 总数超上限、duration ≤ 0、片段重叠等，响应中附具体原因） | 按响应提示修正时间线 |
6004 | 404 | materials[].id 中某个文件不存在 | 检查文件 ID 是否正确、是否已上传 |
6014 | 400 | 素材类型与轨道不匹配（视频轨引用了非视频文件等） | 检查素材类型 |
6502 | 401 | 鉴权失败 | 检查 Authorization 请求头 |
6201 | 402 | 配额不足 | 购买配额包或充值 |
6202 | 402 | 余额不足 | 前往仪表盘充值 |
使用限制
- 单视频轨：本能力只渲染 1 条视频轨——即
track_index最小的 main 底轨；多出的 overlay 视频轨会被忽略。要做多轨叠加 / 画中画 / 颗粒动画，请改走 工程文件生成（导出工程到剪辑软件精修）或 html_animate_render（颗粒合成出片）。音频轨可多条，自动混音。 - 颗粒被忽略：
beat_track在本接口被忽略；请求体可携带它以保持 gtrk 结构完整，但不影响产物。HTML 颗粒请走 html_animate_render。 - 片段数上限：全部轨道 clip 总数 ≤ 500。
- 必然重编码：切点通常不在关键帧上，渲染会重新编码（h264 + aac），耗时与成片时长成正比，建议每 5 ~ 10 秒轮询一次。
- 素材自动归一：不同分辨率 / 帧率的素材会自动缩放、加黑边适配到
video_size并统一帧率，可放心混用异构素材。 - 按输入时长计费：以时间线总时长（= 成片时长，分钟）计费，与素材原始长度无关。
- 与工程文件生成互补：同一份 gtrk v1 时间线（
materials[].id为平台文件 ID）可同时调用两个接口——一边拿工程进剪辑软件精修，一边云端直接出片。