Logo

工程文件生成

将一份 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-Typeapplication/json
鉴权方式Authorization 请求头（直接传 API Key）

请求参数（Body）

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

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

materials[] 素材条目

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

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

  • 本机引用：条目带非空 path（建议绝对路径、一律正斜杠 /；局域网共享上的素材可直接写网络路径 //服务器/共享/…，反斜杠写法 \\服务器\共享\… 同样支持）。此时 id 可为任意本地标识，仅作片段引用键，不做平台文件校验——路径会原样写入产出的工程文件，供你本机剪辑软件加载，请自行保证其在你的环境中有效；
  • 云端引用：条目不带 path。此时 id 必须为平台文件 ID（file_id）且文件需存在，否则返回 6004（文件不存在）。
字段类型必填说明
idstring是素材唯一标识；带 path 时可为任意本地 ID，不带 path 时必须为平台文件 ID（file_id）；被片段以 material 引用
pathstring否本机素材路径（建议绝对路径 + 正斜杠），供 NLE 工程文件 / 离线 ffmpeg 使用；服务端不读取；提供后该条目免平台文件校验
durationnumber否素材总时长（秒）
video_sizearray否素材原始尺寸 [宽, 高]（视频素材）
video_ratenumber否素材帧率（视频素材）
audio_channelstring否声道，取 "stereo" 或 "mono"（音频素材）

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

video_track[] / audio_track[] 轨道对象

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

字段类型必填说明
track_indexnumber是显式层级；最小者为底轨（main）
track_sizearray否（仅视频轨）本轨素材原始尺寸 [宽, 高]，供按画布 video_size 缩放适配
mutedboolean否轨级静音开关（视频轨、音频轨都可带），总开关：为 true 时本轨片段全部静音，clip 级 muted: false 撬不开
volumenumber否轨级默认音量（线性增益），可被 clip 级 volume 覆盖（不相乘）；为兼容旧客户端存档，0 视为原音量、负值按 dB 换算（静音请用 muted）
track_timelinearray是轨道上的片段序列，元素为片段对象。数组顺序无要求（服务端按 track_st 落位）

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

每个非空档片段同时携带源裁剪时码（clip_st/clip_ed）与轨上时码（track_st/track_ed/duration），两套时码冗余保留，方便「按 st+时长」与「按 st+出点」两类客户。track_timeline 的数组顺序无要求：片段一律按 track_st 在时间轴上绝对落位（服务端统一按 track_st 落位），乱序提交与按时间序提交产物一致，片段之间的真实空隙原样保留。

字段类型必填说明
clip_idstring是片段标识；空串 "" 表示空档（Gap），空档不写 material / clip_st / clip_ed
materialstring是引用 materials[].id（空档不写）
clip_stnumber是源素材内的裁剪入点（秒）
clip_ednumber是源素材内的裁剪出点（秒）；变速片段为 clip_st + duration × speed
track_stnumber是片段在时间轴上的入点（秒）
track_ednumber是片段在时间轴上的出点（秒）
durationnumber是片段在时间轴上的时长（秒）
mutedboolean否clip 级静音（video / audio）：只静掉本片段，撬不开已静音的轨
volumenumber否clip 级音量（线性增益；video 片段即原声音量），覆盖轨级 volume、不相乘；为兼容旧客户端存档，0 视为原音量、负值按 dB 换算（静音请用 muted；音量关键帧里的 0 仍是静音端点）
clip_transformobject否（video）clip 静态变换，详见下方「clip_transform 与 clip_keyframes」
clip_keyframesobject否clip 关键帧动画通道（video 全量 / audio 仅音量），详见下方「clip_transform 与 clip_keyframes」
border_radiusnumber否（video）元素显示矩形四角的圆角半径，画布像素、≥ 0，详见下方「border_radius 与 clip_mask」
clip_maskobject否（video）形状蒙版（圆 / 圆角矩形 / 爱心 / 菱形 / 星形），详见下方「border_radius 与 clip_mask」
speednumber否恒定播放速度，0.01–100，缺省 1，详见下方「speed 与 keep_pitch」
keep_pitchboolean否变速时是否保持原音高，缺省 false，详见下方「speed 与 keep_pitch」
audio_fade_innumber否音频淡入时长（秒），≥ 0，缺省 0，详见下方「audio_fade_in 与 audio_fade_out」
audio_fade_outnumber否音频淡出时长（秒），≥ 0，缺省 0，详见下方「audio_fade_in 与 audio_fade_out」
background_fillobject否（video）片段背景填充：纯色或模糊底，铺满画布、只在该片段时长内，详见下方「background_fill」
transition_inobject否（video）片段头部的入场转场，详见下方「转场」
transition_outobject否（video）片段尾部的出场转场，详见下方「转场」
transition_nextobject否（video）与同一条轨上紧邻的下一片段之间的转场，详见下方「转场」

ℹ️ 静音 / 音量双层语义：muted 与 volume 在视频轨、音频轨上都有轨级与 clip 级两层，视频片段上作用于其原声。静音：轨级 muted 是总开关，轨级或 clip 级任一为 true 即静音——clip 级 muted: false 撬不开已静音的轨。音量：clip 级有则用 clip 级，否则用轨级，两级都无则 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 表达。

speed 与 keep_pitch（可选：恒定变速）

video / audio clip 都可带；空档与 beat_track 的 HTML 颗粒不支持变速，带了会被拒绝。缺省即原速。

  • speed：恒定播放速度，有限数，取值 0.01–100。> 1 为快放、< 1 为慢放；
  • duration 是片段在时间轴上的时长，片段消耗的源素材长度为 duration × speed，即 clip_ed = clip_st + duration × speed（按整毫秒计，.5 向上进位）；
  • keep_pitch：布尔，true 表示变速后保持原音高，缺省 false（音高随速度变化）；
  • 关键帧 clip_keyframes 的 t 仍按时间轴上的秒数计，不随速度换算。

各格式承接：剪映草稿与 FCPX 承接速度与保调；CapCut 草稿、Premiere XML、OTIO 承接速度，保调设置无法表达时在返回的 warnings 中按格式计数（kind = speed_keep_pitch_not_carried）；gtrk 原样保留。

// 时间轴上占 3 秒，播放源素材第 10–16 秒，2 倍速、保持音高
{ "clip_id": "c1", "material": "F100", "clip_st": 10.0, "clip_ed": 16.0,
  "track_st": 0.0, "track_ed": 3.0, "duration": 3.0, "speed": 2.0, "keep_pitch": true }

audio_fade_in 与 audio_fade_out（可选：音频淡入淡出）

video / audio clip 都可带；空档与 beat_track 的 HTML 颗粒不支持，带了会被拒绝。缺省（或为 0）即该侧无淡变，转换结果与不带字段完全一致。

  • 取值：秒，有限数，≥ 0，精确到毫秒；
  • 淡入 + 淡出之和不得超过片段时长：两者各自四舍五入到整毫秒（.5 向上进位）后相加，超过 duration（同样取整毫秒）即拒绝请求，不会自动缩短；
  • 曲线为线性（音量幅度从 0 线性升到原音量 / 从原音量线性降到 0），乘在片段音量 volume 与音量关键帧之上；muted 的片段不出声，淡变无效果；
  • 时长按时间轴上的秒数计，不随 speed 换算；
  • video clip 上的淡变只作用于它的原声，画面不变。

各格式承接：

格式音频片段视频片段原声
剪映草稿原生淡入淡出原生淡入淡出
CapCut 草稿原生淡入淡出折成音量关键帧（CapCut 中显示为关键帧而非淡变手柄），warnings 计数 audio_fade_folded_to_keyframes
Premiere XML并入「音频增益（Audio Levels）」包络若音频轨里有它的同源原声片段（同素材、同裁剪、同位置），由该音频片段承接；没有时 Premiere XML 无从出声，warnings 计数 audio_fade_not_carried
FCPX原生线性淡入淡出原生线性淡入淡出
OTIO无标准表达，写入片段 metadata，warnings 计数 audio_fade_not_carried同左（没有同源原声音频片段时）
gtrk原样保留原样保留

上表的告警按格式出现在返回的 warnings 中（format 取值同 files[].format），只返回本次请求格式的条目；剪映、FCPX、gtrk 以及 Premiere 由音频片段承接的情形不产生告警。剪映的原生淡变曲线以剪映自身为准。

// BGM 片段：开头淡入 2 秒、结尾淡出 3 秒
{ "clip_id": "bgm", "material": "F200", "clip_st": 0.0, "clip_ed": 30.0,
  "track_st": 0.0, "track_ed": 30.0, "duration": 30.0, "audio_fade_in": 2.0, "audio_fade_out": 3.0 }

transition_in、transition_out 与 transition_next（可选：转场）

只有视频轨的非空档片段可带三个键；beat_track 的 HTML 颗粒只可带 transition_in / transition_out；音频轨片段与空档不可带。

  • 位置：transition_in 在片段开头，从片段下面的画面过渡到本片段；transition_out 在片段结尾，从本片段过渡到下面的画面；transition_next 挂在前一段上，to_clip_id 指向同一条轨上紧挨着的下一段。一个片段的头、尾各只能有一个转场：带 transition_next 的片段不能再带 transition_out，被它指向的片段不能再带 transition_in。
  • 字段：granule（转场类型，见下）、duration（秒，时间轴上的长度，落在帧格上，不随 speed 换算）、easing（可选，linear / ease-in / ease-out / ease-in-out）、params（可选，各类型的参数）、version（可选，缺省 1）；transition_next 另有 to_clip_id、alignment（可选，0 / 0.5 / 1）与 freeze_fill（可选）。
  • 转场类型：dissolve 叠化、dip-black 闪黑、dip-white 闪白、dip-black-white 黑白闪、dip-white-black 白黑闪、zoom-in 推近、zoom-out 拉远、push-in-subtle 口播轻推、whip 甩镜、push 推移、cover 覆盖、reveal 揭开、wipe 擦除、clock-wipe 时钟擦除、iris 圆形、blur-dissolve 模糊叠化、defocus 虚焦切换、pop 弹入弹出。各类型可放的位置与参数以转场颗粒目录为准。
  • 校验：头尾转场之和不得超过片段长度；to_clip_id 必须是紧挨着的下一段；叠化、擦除、推移这类两段画面同时出现的类型，要求素材在切点外留有余量，不够时请缩短转场或设 freeze_fill: true（不足部分定格首帧 / 尾帧）。不满足即拒绝请求（INVALID_TASK_PARAMS），不会自动缩短。
  • 各格式承接：剪映草稿与 Premiere XML 写入转场——下表的兼容款写成软件自带的对应转场；其余转场在原位置、按原时长换成叠化；叠化在该位置也写不了的（Premiere 中片段头 / 尾紧贴另一片段）才按硬切。CapCut / FCPX / OTIO 暂不写入转场，按硬切。gtrk 原样保留。
  • 告警：在 warnings 中按格式计数，每个转场只计一类，count 为该类转场数：
    • transition_approximated：兼容款按软件默认样式写入（换了颜色的闪黑、选了「收拢」的圆形，或超出剪映能表达的对齐、时长）；
    • transition_substituted：在剪映 / Premiere 里换成了叠化；
    • transition_not_carried：没有写入，按硬切。
转场位置剪映Premiere Pro
dissolve 叠化两段之间、头、尾叠化；头尾为入场「渐显」/ 出场「渐隐」交叉溶解；头尾为单侧交叉溶解（仅当该侧是空档或轨道起止）
dip-black 闪黑两段之间（黑色）闪黑黑场过渡
dip-white 闪白两段之间（白色）闪白白场过渡
push 推移两段之间左移 / 右移 / 上移 / 下移换成叠化（Premiere 的 XML 不支持推）
wipe 擦除两段之间向左 / 向右 / 向上 / 向下擦除划出，方向相同
iris 圆形两段之间（展开）圆形遮罩换成叠化（Premiere 的 XML 不支持圆划像）

剪映的转场只能以切点为中心，且最长为前后两段中较短一段的一半，超出时按此写入并计 transition_approximated。转场两侧素材余量不足时，剪映、Premiere 都会定格首尾帧；Premiere 导入时可能提示「剪辑项上的入点无效」，属正常现象。

// 主轨 A、B 两段之间 0.5 秒闪黑；A 开头 0.3 秒叠化入场
{ "clip_id": "A", "material": "F1", "clip_st": 10.0, "clip_ed": 14.0,
  "track_st": 0.0, "track_ed": 4.0, "duration": 4.0,
  "transition_in": { "granule": "dissolve", "duration": 0.3 },
  "transition_next": { "granule": "dip-black", "duration": 0.5, "to_clip_id": "B" } }

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 个关键帧，可在剪映中继续调整。

background_fill（可选：片段背景填充）

给片段垫一块铺满画布的底：位于该片段所在层的正下方、只在该片段的 track_st–track_ed 内出现。典型用法：窄画幅的 B-roll 放在口播之上时，用纯黑底挡住上下黑边处露出的口播；竖屏片段放进横屏工程时，用模糊底代替两侧黑边。仅 video clip 可带；空档、audio_track、beat_track 上出现会被拒绝（6016）。缺省即不填充。

取值二选一：

  • 纯色：{"type": "color", "color": "#RRGGBB"}，六位十六进制、不带透明度；
  • 模糊：{"type": "blur", "intensity": 200}，intensity 为 0–1000 的整数，模糊源是该片段同一时刻的画面（铺满后模糊）。

这块底不随该片段的 clip_transform / clip_mask / border_radius 走：片段缩成画中画，底仍铺满画布。

各格式承接：

格式最底层视频轨上的片段其它轨上的片段
剪映 / CapCut 草稿原生背景填充；模糊按强度映射到剪映四档：0–124 → 0.0625、125–449 → 0.375、450–799 → 0.75、800–1000 → 1.0在该轨正下方插一条辅助轨：纯色 = 一段等时长的同色纯色图；模糊 = 同一段素材（同一时间段、静音、放大铺满画布）加剪映「模糊」特效
Premiere XML纯黑与序列底色相同，不额外处理；其它纯色在底轨之下插纯色图；模糊 = 同一段素材放大铺满、加高斯模糊，放在底轨之下同剪映「其它轨」，模糊用高斯模糊
FCPXML / OTIO纯黑与序列底色相同，不额外处理；其它纯色在底轨之下插纯色图；模糊改为纯黑纯色同剪映「其它轨」；模糊改为纯黑
gtrk原样保留原样保留

片段自己就铺满画布时（素材宽高比与画布一致，且没有缩小、位移、旋转、半透明、关键帧、蒙版或圆角），底一个像素都露不出来，导出时不额外生成辅助轨。模糊被改为纯黑时（FCPXML / OTIO，或素材缺少尺寸信息无法铺满），返回的 warnings 会按格式给出 background_fill_blur_degraded 与涉及的 clip_ids。纯色图引用的是调用方机器上的文件，需要调用方写出，见下方「写出纯色底图」。

[
  // 主轨一段竖屏素材，两侧用模糊底
  { "clip_id": "m1", "material": "F100", "clip_st": 0.0, "clip_ed": 6.0,
    "track_st": 0.0, "track_ed": 6.0, "duration": 6.0,
    "background_fill": { "type": "blur", "intensity": 200 } },
  // 叠加轨上一段窄画幅 B-roll，下面垫纯黑
  { "clip_id": "b1", "material": "F200", "clip_st": 5.0, "clip_ed": 8.0,
    "track_st": 12.0, "track_ed": 15.0, "duration": 3.0,
    "background_fill": { "type": "color", "color": "#000000" } }
]

struct_meta 对象

字段类型必填说明
nle_draft_dirstring否剪映 / CapCut 草稿的落盘目录绝对路径。旧名 capcut_draft_path 作为兼容别名继续接受
nle_asset_dirstring否工程文件引用的辅助素材在调用方机器上的落盘目录（绝对路径）。目前只用于片段背景填充的纯色图，见下方「写出纯色底图」；不传时回落 nle_draft_dir，两者都没有则不生成纯色图
client_visual_elementsobject否客户端字幕等叠加元素的镜像。其中字幕（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 种：

值产物保存为
xmlPremiere / FCP7 XML.xml
fcpxmlFinal Cut Pro X.xml
otioOpenTimelineIO.json
jianying剪映草稿（自动成对产出）draft_content.json + draft_meta_info.json
capcutCapCut 草稿（自动成对产出）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）

参数名类型说明
filesarray成功产出的工程文件列表
files[].formatstring产物格式：xml / fcpxml / otio / gtrk / jianying_draft / jianying_meta / capcut_draft / capcut_meta
files[].file_idstring产物文件 ID
files[].download_urlstring下载路径
files[].filenamestring建议文件名（如 draft_content.json，放入草稿文件夹后软件才识别）
errorsobject失败的格式及原因（部分成功时非空）
warningsarray非阻断告警列表，可为空；任务 completed 不代表没有告警。告警不等同于 errors 中的格式生成失败
warnings[].formatstring可选。告警针对的产物格式，取值同 files[].format（如 CapCut 草稿为 capcut_draft）；只返回本次请求格式的告警。不针对单一格式的告警不带此字段
materialize_filesarray可选，仅片段背景填充生成了纯色图时出现。工程文件已按这些路径引用纯色 PNG，调用方须写出，见下方「写出纯色底图」
materialize_files[].pathstring纯色图在调用方机器上的路径（<nle_asset_dir>/solid-<rrggbb>-<宽>x<高>.png，正斜杠）
materialize_files[].kindstring固定为 solid
materialize_files[].colorstring颜色，#RRGGBB
materialize_files[].width / heightnumber图片尺寸，等于工程画布 video_size
materialize_files[].formatsarray用得到这张图的产物格式（取值同 files[].format）；只列本次请求格式用得到的图

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

字幕正文键缺失告警

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

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

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

片段背景填充告警

{"kind": "background_fill_blur_degraded", "format": "xml", "count": 1, "clip_ids": ["b1"], "message": "1 个片段的模糊底已改为纯黑…"}
  • background_fill_blur_degraded：这些片段的模糊底已改为纯黑——FCPX / OTIO 不支持背景模糊；剪映 / CapCut / Premiere 只有在素材缺少尺寸信息、无法铺满时才会出现。
  • background_fill_not_materialized：请求既没给 nle_asset_dir 也没给 nle_draft_dir，这些片段的纯色底没能生成，它们之下会露出下层画面。

写出纯色底图

剪映 / Premiere 等软件只能引用本机文件，所以片段背景填充生成的纯色图，要由调用方在写入工程文件时一并写出：

  1. 请求时在 struct_meta.nle_asset_dir 给出落盘目录（剪映可直接用草稿目录，Premiere 可用导出 XML 所在目录）；
  2. 任务完成后，按 materialize_files 逐条生成一张纯色 PNG（尺寸 width × height、颜色 color），写到 path；同色同尺寸只需一张；
  3. 先写图、再写工程文件，避免软件打开时找不到图。为安全起见，只写落在你自己给出的目录里、文件名与颜色和尺寸对得上的条目。

成功响应示例

{
  "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 状态码说明解决方案
6013400必填参数缺失（video_size/video_rate/duration/materials/video_track/audio_track）补齐必填参数
6004400云端引用的素材文件不存在（不带 path 的条目 id 未命中平台文件）核对 file_id，或为本机素材补 path 走本机引用
6016400参数类型或结构非法（如 material 不在 materials 列表中、project_formats 含非法值、background_fill 形状不对或出现在空档 / 音频轨 / beat_track 上）检查时间线结构与取值
6502401鉴权失败检查 Authorization 请求头
6201402配额不足购买配额包或充值
6202402余额不足前往仪表盘充值

使用限制

  • 纯结构转换：服务端不读取 materials[].path 指向的素材文件，仅把路径写入工程文件。请确保这些路径在你的剪辑环境中有效。
  • Premiere 重新链接请核对路径：Premiere 打开 XML 时若弹出「链接媒体」框（素材被移动、改名，或路径在本机无效），链接前请先确认目标文件。勾选「自动重新链接其他媒体」时，Premiere 会按文件名在你选定的位置查找其余缺失素材并自动链上，链错也不会提示；不同工程里同名素材很常见（素材常以编号命名），链接后请在项目面板的「媒体路径」列逐条核对，拿不准时取消该选项、逐个链接。
  • 颗粒不在此渲染：beat_track 在本接口被忽略，HTML 颗粒请走 html_animate_render。
  • 按次计费：一次请求计费一次，不因同时产出多个格式而重复计费。
  • 草稿版本兼容：生成的剪映 / CapCut 草稿需用兼容版本的客户端打开（草稿结构随软件版本演进）；将 draft_content.json 与 draft_meta_info.json 放入对应草稿文件夹后即可在软件中打开继续编辑。
  • 草稿元信息：仅当传入 struct_meta.nle_draft_dir 时才产出 jianying_meta / capcut_meta；不传则只产内容文件，软件可能打不开。
  • 纯色底图不要挪走：片段背景填充生成的纯色图按绝对路径被工程引用，挪动或删除 nle_asset_dir 里的这些图，软件里对应片段的底会显示为缺失素材。