工程文件生成

将一份 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。

字段	类型	必填	说明
`id`	`string`	是	素材唯一标识；云端即文件 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_timeline[] 片段对象（video / audio）

每个非空档片段同时携带源裁剪时码（clip_st/clip_ed）与轨上时码（track_st/track_ed/duration），两套时码冗余保留，方便「按 st+时长」与「按 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`

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

struct_meta 对象

字段	类型	必填	说明
`nle_draft_dir`	`string`	否	剪映 / CapCut 草稿的落盘目录绝对路径。旧名 `capcut_draft_path` 作为兼容别名继续接受

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

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 等）继续接受且维持只产单文件的原语义，新接入请使用上表枚举。

请求示例

下例演示一个源剪多段：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`	失败的格式及原因（部分成功时非空）

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

成功响应示例

{
  "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`）	补齐必填参数
`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；不传则只产内容文件，软件可能打不开。