工程文件生成

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

与其他接口不同，本接口无需上传文件：请求体本身就是时间线结构。material_map 中的素材路径是调用方剪辑环境内的本地引用，服务端不读取素材文件，仅做结构转换。

创建任务

基本信息

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

请求参数（Body）

请求体即时间线结构：

参数名	类型	必填	默认值	说明
video_size	array	是	—	画布尺寸 [宽, 高]（像素），如 [1920, 1080]
video_rate	number	是	—	整体帧率（fps），如 60
video_track	array	是	—	视频轨列表，每条含 track_size 与 track_timeline，详见下表
audio_track	array	是	—	音频轨列表，每条含 track_timeline
material_map	object	是	—	素材元数据映射，详见下表
struct_meta	object	否	{}	含 capcut_draft_path（草稿落盘目录）；缺省时不产出草稿 meta
output_formats	array	否	全部	指定要产出的格式子集；缺省即产出全部 7 种

video_track[] / audio_track[] 中的轨道对象

字段	类型	说明
track_size	array	（仅视频轨）本轨素材原始尺寸 [宽, 高]，用于缩放适配
track_timeline	array	轨道上的片段序列，元素为片段对象

track_timeline[] 中的片段对象

字段	类型	说明
clip_id	string	素材 ID（对应 material_map）；空串 "" 表示空档（Gap）
clip_st	number	取用素材内的起始时间（秒）
clip_ed	number	取用素材内的结束时间（秒）
track_st	number	片段在时间轴上的起始时间（秒）
track_ed	number	片段在时间轴上的结束时间（秒）
duration	number	片段时长（秒）

material_map 字段

字段	类型	说明
path	object	{素材ID: 素材路径}，路径为调用方本地引用，服务端不读取
duration	object	{素材ID: 素材总时长(秒)}
video_rate	object	{素材ID: 帧率}（仅视频素材）
audio_channel	object	{素材ID: "stereo"|"mono"}（仅音频素材）
video_size	object	{素材ID: [宽,高]}（仅视频素材）

output_formats 可选值

值	产物	保存为
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

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

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/video_project_struct \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_size": [1920, 1080],
    "video_rate": 60,
    "video_track": [
      {
        "track_size": [1920, 1080],
        "track_timeline": [
          {"clip_id": "v1", "clip_st": 10.0, "clip_ed": 13.45, "track_st": 0.0, "track_ed": 3.45, "duration": 3.45},
          {"clip_id": "", "clip_st": 0, "clip_ed": 0, "track_st": 3.45, "track_ed": 5.45, "duration": 2.0}
        ]
      }
    ],
    "audio_track": [
      {"track_timeline": [{"clip_id": "a1", "clip_st": 0.0, "clip_ed": 3.45, "track_st": 0.0, "track_ed": 3.45, "duration": 3.45}]}
    ],
    "material_map": {
      "path": {"v1": "C:/clips/v1.mp4", "a1": "C:/clips/a1.mp3"},
      "duration": {"v1": 60, "a1": 180},
      "video_rate": {"v1": 60},
      "audio_channel": {"a1": "stereo"},
      "video_size": {"v1": [1920, 1080]}
    },
    "struct_meta": {"capcut_draft_path": "C:/Users/Me/AppData/Local/JianyingPro/User Data/Projects/com.lveditor.draft/20250101"},
    "output_formats": ["xml", "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 / 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": "jianying_draft", "file_id": "537489015178249", "download_url": "/download/a2/537489015178249.json", "filename": "draft_content.json"},
        {"format": "jianying_meta", "file_id": "537489015178250", "download_url": "/download/a3/537489015178250.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/video_track/audio_track/material_map）	补齐必填参数
6016	400	参数类型或结构非法（如 clip_id 不在 material_map.path 中、output_formats 含非法值）	检查时间线结构与取值
6502	401	鉴权失败	检查 Authorization 请求头
6201	402	配额不足	购买配额包或充值
6202	402	余额不足	前往仪表盘充值

使用限制

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