工程文件生成

将一份 gtrk v1 时间线结构 转换为多种非线性剪辑（NLE）软件的工程文件，一次生成 Premiere/FCP7 XML、Final Cut Pro X、OpenTimelineIO、剪映草稿、CapCut 草稿与同合云 gtrk 工程文件。适用于把算法编排好的视频结构一键导入到剪辑软件中继续精修。

ℹ️ 说明：与其他接口不同，本接口无需上传文件——请求体本身就是时间线结构。materials[].path 中的素材路径是调用方剪辑环境内的本地引用，服务端不读取素材文件，仅做结构转换；materials[].id 在云端场景即平台返回的文件 ID（file_id）。

创建任务

基本信息

项目	值
请求方法	`POST`
请求路径	`/task/video_project_struct`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头（直接传 API Key）

请求参数（Body）

请求体即一份 gtrk v1 时间线结构。所有时间字段单位均为秒。

参数名	类型	必填	默认值	说明
`version`	`string`	是	—	契约版本，固定为 `"v1"`
`video_size`	`array`	是	—	画布尺寸 `[宽, 高]`（像素），如 `[1920, 1080]`
`video_rate`	`number`	是	—	整体帧率（fps，整数），如 `60`
`duration`	`number`	是	—	成片总时长（秒）
`materials`	`array`	是	—	素材清单（列表），每条含 `id` 及元数据，详见下表
`video_track`	`array`	是	—	视频轨列表（分层），详见下表
`audio_track`	`array`	是	—	音频轨列表（分层），详见下表
`beat_track`	`array`	否	`[]`	HTML 颗粒叠加层。本接口忽略 `beat_track`，要渲染颗粒请走 html_animate_render
`struct_meta`	`object`	否	`{}`	含 `nle_draft_dir`（草稿落盘目录），详见下表
`project_formats`	`array`	否	全部	指定要产出的格式子集；缺省即产出全部公开格式。旧名 `output_formats` 作为兼容别名继续接受

materials[] 素材条目

每条素材以单一 id 标识——云端场景即平台 file_id，纯本地场景可为本地 ID。素材在 video_track / audio_track / beat_track 的片段里以 material 字段引用此 id。

素材条目按引用形态二选一，同一请求可混用：

本机引用：条目带非空 path（建议绝对路径、一律正斜杠 /）。此时 id 可为任意本地标识，仅作片段引用键，不做平台文件校验——路径会原样写入产出的工程文件，供你本机剪辑软件加载，请自行保证其在你的环境中有效；
云端引用：条目不带 path。此时 id 必须为平台文件 ID（file_id）且文件需存在，否则返回 6004（文件不存在）。

字段	类型	必填	说明
`id`	`string`	是	素材唯一标识；带 `path` 时可为任意本地 ID，不带 `path` 时必须为平台文件 ID（`file_id`）；被片段以 `material` 引用
`path`	`string`	否	本机素材路径（建议绝对路径 + 正斜杠），供 NLE 工程文件 / 离线 ffmpeg 使用；服务端不读取；提供后该条目免平台文件校验
`duration`	`number`	否	素材总时长（秒）
`video_size`	`array`	否	素材原始尺寸 `[宽, 高]`（视频素材）
`video_rate`	`number`	否	素材帧率（视频素材）
`audio_channel`	`string`	否	声道，取 `"stereo"` 或 `"mono"`（音频素材）

💡 提示：尽量为每条素材填齐可得的元数据，持有 gtrk 的客户即可离线用 ffmpeg 自洽重建工程、无需回云解析 ID。某项缺失不会中断序列化，仅令该项缺位。

video_track[] / audio_track[] 轨道对象

视频轨与音频轨都按层级分轨：track_index 是显式 z 层级整数，track_index 最小那条即底轨（main），其余为叠加层（track_index 越大越靠前）。

字段	类型	必填	说明
`track_index`	`number`	是	显式层级；最小者为底轨（main）
`track_size`	`array`	否	（仅视频轨）本轨素材原始尺寸 `[宽, 高]`，供按画布 `video_size` 缩放适配
`muted`	`boolean`	否	（仅视频轨）轨级默认静音态，可被 clip 级 `muted` 覆盖
`volume`	`number`	否	（仅音频轨）轨级默认音量，可被 clip 级 `volume` 覆盖
`track_timeline`	`array`	是	轨道上的片段序列，元素为片段对象。数组顺序无要求（服务端按 `track_st` 落位）

track_timeline[] 片段对象（video / audio）

每个非空档片段同时携带源裁剪时码（clip_st/clip_ed）与轨上时码（track_st/track_ed/duration），两套时码冗余保留，方便「按 st+时长」与「按 st+出点」两类客户。track_timeline 的数组顺序无要求：片段一律按 track_st 在时间轴上绝对落位（服务端统一按 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`	是	片段时长（秒）
`muted`	`boolean`	否	（video）clip 级静音，覆盖轨级 `muted`
`volume`	`number`	否	（audio）clip 级音量，覆盖轨级 `volume`
`clip_transform`	`object`	否	（video）clip 静态变换，详见下方「clip_transform 与 clip_keyframes」
`clip_keyframes`	`object`	否	clip 关键帧动画通道（video 全量 / audio 仅音量），详见下方「clip_transform 与 clip_keyframes」
`border_radius`	`number`	否	（video）元素显示矩形四角的圆角半径，画布像素、≥ 0，详见下方「border_radius 与 clip_mask」
`clip_mask`	`object`	否	（video）形状蒙版（圆 / 圆角矩形 / 爱心 / 菱形 / 星形），详见下方「border_radius 与 clip_mask」

ℹ️ 静音 / 音量双层语义：视频用 muted、音频用 volume，轨级与 clip 级各一层。优先级为：clip 级有则用 clip 级，否则用轨级，两级都无则缺省（muted 缺省 false、volume 缺省 1.0）。

clip_transform 与 clip_keyframes（可选：静态变换与关键帧动画）

两个字段都仅剪映 / CapCut 草稿承接，其余格式（Premiere / FCPX / OTIO）忽略、不报错；缺省即无变换 / 无动画。

clip_transform（静态变换，video clip）：{position_x, position_y, scale_x, scale_y, rotation, alpha}。单位：position_x/y 画布像素（画布中心为原点，+x 向右 / +y 向下）；scale_x/y 比例（1.0 = 100%，负值 = 翻转）；rotation 顺时针角度（deg）；alpha 不透明度 0..1。

clip_keyframes（关键帧动画）：对象，键为属性名、值为非空 [{t, v}] 数组。video clip 支持 position_x / position_y / scale_x / scale_y / rotation / alpha / volume 七个通道；audio clip 仅支持 volume（音量渐变）。取值规则：

t 为相对该 clip 在轨上入点的秒数，须落在 [0, duration] 内且同通道严格递增；
v 单位与 clip_transform 同名属性一致（volume 为线性增益、须 ≥ 0，1.0 = 原音量）；
相邻关键帧之间线性插值（剪映草稿的关键帧插值即线性）；
单通道最多 3000 个关键帧；
某属性带关键帧时，建议把 clip_transform 对应静态值设为首个关键帧的值（剪映内以关键帧曲线为准，静态值供不承接动画的格式兜底）；
scale_x / scale_y 通道含负值时该通道不承接（剪映的翻转是开关量、无法打关键帧），clip 其余通道照常转换；静态翻转请用 clip_transform 的负值 scale 表达。

border_radius 与 clip_mask（可选：圆角与形状蒙版）

两个字段仅 video clip 可带（audio clip 带任一字段会被拒绝），仅剪映 / CapCut 草稿承接，其余格式忽略、不报错；缺省即无圆角 / 无蒙版。典型用法是画中画：用 clip_transform 缩放定位，再用 border_radius 给画中画圆角，或用 clip_mask 开一个圆形窗。

border_radius（圆角）：≥ 0 的数值，单位为画布像素，作用于该 clip 在画布上的显示矩形（缩放后）的四角，随 clip 一起旋转。剪映内以一个满幅圆角矩形蒙版表达。

clip_mask（形状蒙版，每个 clip 最多一个）：{shape, center_x, center_y, width, height, rotation, corner_radius, feather, invert}。

shape：rectangle（矩形，可配 corner_radius）/ ellipse（椭圆，宽高相等即正圆）/ heart / diamond / star；
center_x / center_y：蒙版中心，相对 clip 显示矩形归一化、以中心为原点——0 为中心、±0.5 为边界，+x 向右 / +y 向下，允许超出边界；缺省 0；
width / height：蒙版宽高，相对 clip 显示宽 / 高的比例（> 0，可大于 1）；缺省 0.5；
rotation：绕蒙版中心的顺时针角度（deg）；
corner_radius：仅 rectangle，0..1，圆角半径占蒙版短边一半的比例（1 = 全圆角）；
feather：0..100，羽化带宽占蒙版短边的百分比（0 = 硬边）；
invert：布尔，反相（保留蒙版外、遮住蒙版内）。

转换口径：剪映的椭圆 / 爱心 / 星形是固定宽高比的形状，width 与 height 不匹配时按 height 承接；diamond 剪映无对应形状，该 clip 的蒙版跳过、其余字段照常；同一 clip 同时给了 border_radius 与 clip_mask 时，剪映内只挂 clip_mask（一个片段只能有一个蒙版）；素材缺少 video_size 时蒙版无法换算、跳过。

{
  "clip_id": "c1", "material": "F100",
  "clip_st": 0.0, "clip_ed": 4.0, "track_st": 0.0, "track_ed": 4.0, "duration": 4.0,
  "clip_transform": { "alpha": 0.0 },
  "clip_keyframes": {
    "alpha":      [ { "t": 0.0, "v": 0.0 }, { "t": 1.0, "v": 1.0 } ],
    "position_y": [ { "t": 0.0, "v": 270 }, { "t": 1.0, "v": 0 } ]
  }
}

上例为「淡入 + 从下方 270px 滑入」：导出剪映后该片段带 4 个关键帧，可在剪映中继续调整。

struct_meta 对象

字段	类型	必填	说明
`nle_draft_dir`	`string`	否	剪映 / CapCut 草稿的落盘目录绝对路径。旧名 `capcut_draft_path` 作为兼容别名继续接受
`client_visual_elements`	`object`	否	客户端字幕等叠加元素的镜像。其中字幕（text）会被装配成剪映草稿里的一条文本轨——可在剪映内选中、改字、继续调样式。详见下方「字幕文本轨」

⚠️ nle_draft_dir 是什么：它就是剪映 / CapCut 草稿要落盘的那个草稿文件夹的绝对路径。剪映 / CapCut 靠成对的 draft_content.json + draft_meta_info.json 放在这个目录里来识别一份草稿。不传该路径，本接口只产出 draft_content.json（内容文件），缺了 draft_meta_info.json（元信息），软件可能打不开这份草稿。 因此要在剪映 / CapCut 里打开成品草稿，请务必传 nle_draft_dir。

字幕文本轨（`struct_meta.client_visual_elements`）

传入该字段时，其中的字幕元素会被装配成剪映草稿的一条文本轨，落在全部视频轨之上，用户在剪映里可以直接选中、改字、继续调样式；字幕以「字幕」身份进入剪映（可用剪映的字幕批量编辑面板），折行交由剪映按行宽自动处理。

只有剪映（jianying）承接字幕文本轨，其余产出格式一律不承接，理由各不相同：

格式	是否承接字幕	原因
`jianying`	✅ 承接	—
`capcut`	❌ 不承接	目标库能力所限（缺阴影 API、字体表无所需中文字体）
`xml`（Premiere）	❌ 不承接	本接口的 Premiere 产出链尚无文本词汇，后续可支持
`fcpxml`	❌ 不承接	同上，且字幕需引用本机模板资源、跨机不稳
`otio`	❌ 不承接	格式本身没有文本/字幕结构

⚠️ 时间单位必须显式声明：该对象的 time_unit 字段须为 "second"（秒）。取其它值或不传时，本接口不会装配字幕轨——这是刻意的保护：按错误单位解释时间会产出「结构正确但时间全错」的草稿（能打开、但字幕全在片尾之外）。

体量上限：最多 200 条叠加轨 / 2000 个元素 / 2 MB。超限返回参数错误。

样式承接以你在客户端当刻的实际参数为准（改过的样式会跟着走）；剪映无法表达的维度（如字形非等比缩放）不做近似冒充，会跳过并记录。贴纸 / 图形 / 特效不进草稿，但会在产出记录里留下跳过计数。

beat_track[] 颗粒叠加层

beat_track 用于承载 HTML 动画颗粒叠加层。本「工程文件生成」接口会忽略 beat_track——NLE 工程文件不承载 HTML 颗粒。要把颗粒真正渲染进画面，请改走 html_animate_render。请求体可以携带 beat_track 以保持 gtrk 结构完整，但它不会影响本接口的产物。

project_formats 可选值

公开产出格式共 6 种：

值	产物	保存为
`xml`	Premiere / FCP7 XML	`.xml`
`fcpxml`	Final Cut Pro X	`.xml`
`otio`	OpenTimelineIO	`.json`
`jianying`	剪映草稿（自动成对产出）	`draft_content.json` + `draft_meta_info.json`
`capcut`	CapCut 草稿（自动成对产出）	`draft_content.json` + `draft_meta_info.json`
`gtrk`	同合云工程文件（单索引 JSON，供同合云客户端导入）	`.gtrk`

ℹ️ 说明：剪映 / CapCut 草稿需要内容与元信息两个文件成对放入草稿文件夹才能被软件识别，因此选 jianying / capcut 即自动产出两个文件。出参 files[].format 仍按文件细分（如 jianying_draft / jianying_meta）。兼容说明：旧版细粒度值（jianying_draft 等）继续接受且维持只产单文件的原语义，新接入请使用上表枚举。

🆕 草稿默认开启「自由层级」：本接口产出的剪映 / CapCut 草稿默认以自由层级模式打开，片段层级可自由调整，不受传统「主轨 + 画中画」层级模型约束；多轨叠放次序与此前一致。

⚠️ 此前导出的旧草稿无法改回：剪映在导入草稿时即锁定层级模式，之后无法在工程设置里切换。若你手上的旧草稿需要自由层级，请重新导出一次。

请求示例

下例演示一个源剪多段：materials 只声明一条视频源，video_track 用同一素材的不同 clip_st / clip_ed 切出多段拼接，再叠一条 audio_track，并指定 project_formats。

curl -X POST https://api.ai-mcn.tv:10000/task/video_project_struct \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1",
    "video_size": [1920, 1080],
    "video_rate": 60,
    "duration": 9.0,
    "materials": [
      {
        "id": "F100",
        "path": "C:/clips/source.mp4",
        "duration": 120.0,
        "video_size": [1920, 1080],
        "video_rate": 60,
        "audio_channel": "stereo"
      },
      {
        "id": "F200",
        "path": "C:/clips/bgm.mp3",
        "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": 10.0, "clip_ed": 13.0,
            "track_st": 0.0, "track_ed": 3.0, "duration": 3.0
          },
          {
            "clip_id": "c2", "material": "F100",
            "clip_st": 55.0, "clip_ed": 59.0,
            "track_st": 3.0, "track_ed": 7.0, "duration": 4.0,
            "muted": true
          },
          {
            "clip_id": "c3", "material": "F100",
            "clip_st": 88.0, "clip_ed": 90.0,
            "track_st": 7.0, "track_ed": 9.0, "duration": 2.0
          }
        ]
      }
    ],
    "audio_track": [
      {
        "track_index": 0,
        "volume": 0.8,
        "track_timeline": [
          {
            "clip_id": "a1", "material": "F200",
            "clip_st": 0.0, "clip_ed": 9.0,
            "track_st": 0.0, "track_ed": 9.0, "duration": 9.0
          }
        ]
      }
    ],
    "struct_meta": {
      "nle_draft_dir": "C:/Users/Me/AppData/Local/JianyingPro/User Data/Projects/com.lveditor.draft/20260626"
    },
    "project_formats": ["xml", "gtrk", "jianying"]
  }'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "task_type": "video_project_struct",
    "status": "queued"
  }
}

查询任务结果

基本信息

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

响应参数（output_result）

参数名	类型	说明
`files`	`array`	成功产出的工程文件列表
`files[].format`	`string`	产物格式：`xml` / `fcpxml` / `otio` / `gtrk` / `jianying_draft` / `jianying_meta` / `capcut_draft` / `capcut_meta`
`files[].file_id`	`string`	产物文件 ID
`files[].download_url`	`string`	下载路径
`files[].filename`	`string`	建议文件名（如 `draft_content.json`，放入草稿文件夹后软件才识别）
`errors`	`object`	失败的格式及原因（部分成功时非空）
`warnings`	`array`	非阻断告警列表，可为空；任务 `completed` 不代表没有告警。告警不等同于 `errors` 中的格式生成失败

ℹ️ 部分成功：各格式相互独立生成，单个格式失败不影响其余格式，任务仍标记为 completed，失败项记录在 errors 中；仅当全部格式都失败时任务才标记为 failed。

字幕正文键缺失告警

当参与字幕解析的文本元素缺少 params.content 键时，warnings 会包含以下条目：

{"kind": "text_content_key_missing", "count": 2, "total": 10}

count：缺少正文键的文本段数。这些段会按空正文跳过，草稿仍可能生成成功，但缺少相应字幕。
total：参与本次字幕解析的文本段总数，不是最终生成的字幕数。
处理方式：检查发送端的文本参数映射，保留 params.content 键名；不要因任务完成而忽略此告警。

正文键存在但内容为空时，不触发这个告警；普通格式不承接字幕也不会因此产生这个告警。正常承接字幕不会生成“字幕已进入草稿”的成功提示。

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "files": [
        {"format": "xml", "file_id": "537489015178248", "download_url": "/download/a1/537489015178248.xml", "filename": "premiere.xml"},
        {"format": "gtrk", "file_id": "537489015178249", "download_url": "/download/a2/537489015178249.gtrk", "filename": "project.gtrk"},
        {"format": "jianying_draft", "file_id": "537489015178250", "download_url": "/download/a3/537489015178250.json", "filename": "draft_content.json"},
        {"format": "jianying_meta", "file_id": "537489015178251", "download_url": "/download/a4/537489015178251.json", "filename": "draft_meta_info.json"}
      ],
      "errors": {}
    },
    "create_time": "2026-06-01T08:00:00Z",
    "update_time": "2026-06-01T08:00:03Z"
  }
}

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	必填参数缺失（`video_size`/`video_rate`/`duration`/`materials`/`video_track`/`audio_track`）	补齐必填参数
`6004`	400	云端引用的素材文件不存在（不带 `path` 的条目 `id` 未命中平台文件）	核对 `file_id`，或为本机素材补 `path` 走本机引用
`6016`	400	参数类型或结构非法（如 `material` 不在 `materials` 列表中、`project_formats` 含非法值）	检查时间线结构与取值
`6502`	401	鉴权失败	检查 `Authorization` 请求头
`6201`	402	配额不足	购买配额包或充值
`6202`	402	余额不足	前往仪表盘充值

使用限制

纯结构转换：服务端不读取 materials[].path 指向的素材文件，仅把路径写入工程文件。请确保这些路径在你的剪辑环境中有效。
颗粒不在此渲染：beat_track 在本接口被忽略，HTML 颗粒请走 html_animate_render。
按次计费：一次请求计费一次，不因同时产出多个格式而重复计费。
草稿版本兼容：生成的剪映 / CapCut 草稿需用兼容版本的客户端打开（草稿结构随软件版本演进）；将 draft_content.json 与 draft_meta_info.json 放入对应草稿文件夹后即可在软件中打开继续编辑。
草稿元信息：仅当传入 struct_meta.nle_draft_dir 时才产出 jianying_meta / capcut_meta；不传则只产内容文件，软件可能打不开。

工程文件生成

创建任务

基本信息

请求参数（Body）

materials[] 素材条目

video_track[] / audio_track[] 轨道对象

track_timeline[] 片段对象（video / audio）

clip_transform 与 clip_keyframes（可选：静态变换与关键帧动画）

border_radius 与 clip_mask（可选：圆角与形状蒙版）

struct_meta 对象

字幕文本轨（struct_meta.client_visual_elements）

beat_track[] 颗粒叠加层

project_formats 可选值

请求示例

成功响应示例

查询任务结果

基本信息

响应参数（output_result）

字幕正文键缺失告警

成功响应示例

错误码

使用限制

字幕文本轨（`struct_meta.client_visual_elements`）