工程文件生成

将一份通用的时间线结构转换为多种非线性剪辑（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`	剪映草稿内容	`draft_content.json`
`jianying_meta`	剪映草稿元信息	`draft_meta_info.json`
`capcut_draft`	CapCut 草稿内容	`draft_content.json`
`capcut_meta`	CapCut 草稿元信息	`draft_meta_info.json`

请求示例

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_draft", "jianying_meta"]
  }'

成功响应示例

{
  "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。