剪映草稿管理接口使用教程

剪映草稿管理接口详解

剪映草稿管理API接口，表面上功能繁多，但核心仅包含三项：创建草稿、保存草稿和获取草稿文件列表。本文将彻底拆解这些功能，从请求方法、参数校验，到错误处理与最佳实践，一次性讲透。先上一张整体架构图，助你建立全局认知。

核心接口概览

整套接口严格遵循RESTful设计规范，结构清晰。三个核心API完美覆盖草稿的整个生命周期：

graph TBClient["客户端"] --> Create["创建草稿
POST /v1/create_draft"]Client --> Sa ve["保存草稿
POST /v1/sa ve_draft"]Client --> Get["获取草稿文件
GET /v1/get_draft"]Create --> Service1["服务层
create_draft.py"]Sa ve --> Service2["服务层
sa ve_draft.py"]Get --> Service3["服务层
get_draft.py"]Service1 --> Cache["缓存
draft_cache.py"]Service2 --> CacheService3 --> Config["配置
config.py"]Cache --> FS["文件系统
DRAFT_DIR"]Config --> FS

接口详细说明

接下来，逐一深入拆解各个接口的细节。

接口一：创建草稿

HTTP请求方法与路径
POST /openapi/capcut-mate/v1/create_draft

功能描述
基于预设模板初始化一个全新的剪映草稿项目。支持自定义画布宽度和高度，返回草稿URL及帮助文档链接，方便后续编辑与调用。

请求参数

• width：数值类型，必须≥1，默认1920
• height：数值类型，必须≥1，默认1080

响应字段

• draft_url：草稿访问地址，格式示例 .../get_draft?draft_id=2025...
• tip_url：帮助文档链接

错误处理

• 400：参数类型不合法或超出范围
• 500：服务器内部异常
• 503：服务暂时不可用

创建草稿工作流程

flowchart TDStart(["开始"]) --> Parse["解析请求参数
width/height"]Parse --> Validate{"参数合法？"}Validate --> |否| ErrParam["返回400 参数错误"]Validate --> |是| CopyTpl["复制模板到草稿目录"]CopyTpl --> InitCanvas["设置画布尺寸"]InitCanvas --> AddTrack["添加空主轨道"]AddTrack --> Sa ve["保存草稿"]Sa ve --> Cache["更新缓存"]Cache --> BuildURL["生成草稿URL"]BuildURL --> Done(["结束"])ErrParam --> Done

接口二：保存草稿

HTTP请求方法与路径
POST /openapi/capcut-mate/v1/sa ve_draft

功能描述

将当前内存中的编辑状态持久化写入磁盘，确保所有修改不会丢失。建议在每次完成编辑操作后及时调用。

请求参数

• draft_url：草稿URL，必填

响应字段

• draft_url：保存后的草稿URL

错误处理

• 400：缺少或格式无效的draft_url
• 404：草稿不存在
• 500：保存失败
• 503：服务不可用

保存草稿工作流程

flowchart TDStart(["开始"]) --> ParseURL["解析 draft_url 获取 draft_id"]ParseURL --> CheckCache{"缓存中存在？"}CheckCache --> |否| ErrNotFound["返回404 草稿不存在"]CheckCache --> |是| Load["从缓存加载草稿对象"]Load --> Sa ve["调用 sa ve() 持久化"]Sa ve --> Done(["结束"])ErrNotFound --> Done

接口三：获取草稿文件列表

HTTP请求方法与路径
GET /openapi/capcut-mate/v1/get_draft

功能描述

根据草稿ID，获取该草稿下的所有文件列表。适用于内容预览、文件管理及状态检查等场景。

请求参数

• draft_id：字符串，必填，长度范围20至32

响应字段

• files：文件URL列表（基于DOWNLOAD_URL拼接而成）

错误处理

• 400：缺少或格式无效的draft_id
• 404：草稿不存在
• 500：获取失败
• 503：服务不可用

获取草稿文件列表工作流程

flowchart TDStart(["开始"]) --> ValidateID["校验 draft_id 非空且长度20-32"]ValidateID --> Exists{"草稿目录存在？"}Exists --> |否| ErrNotFound["返回404 草稿不存在"]Exists --> |是| Scan["遍历草稿目录获取文件列表"]Scan --> BuildURL["批量生成下载URL"]BuildURL --> Done(["结束"])ErrNotFound --> Done

草稿URL生成规则

草稿URL的生成方式相对简单：基于配置中的DRAFT_URL，拼接一个draft_id参数。该draft_id由时间戳与随机十六进制数构成，确保全局唯一。

URL格式
https://域名/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258

有效期
生成的 draft_url 并非永久有效，请注意它的有效期限。

文件结构说明

创建草稿后，文件具体存放在哪个目录？结构如何？

• 草稿目录结构：output/draft/{draft_id}/
• 核心文件：draft_info.json（模板元信息）和 draft_content.json（内容脚本），除此之外还有其他素材与配置文件。
• 模板来源：template/default2/ 是初始模板目录，创建草稿时会复制一份到草稿目录。这也意味着每次创建草稿都是全新的起点。
• 双文件兼容模式：draft_info.json 与 draft_content.json 会同步更新，确保数据一致性，这是非常关键的设计。

最佳实践

结合实战经验，以下建议可帮你有效规避常见问题：

• 参数验证：确保 width 和 height 均为正整数，建议直接采用常见的视频分辨率，避免使用过于冷门的尺寸，否则后续编辑可能非常麻烦。
• 调用顺序：先调用创建草稿接口获取草稿URL和ID，再进行编辑操作。保存操作应频繁触发，切勿等全部编辑完成后才一次性保存，中途断电或异常会导致数据丢失。
• 性能考虑：避免设置超高分辨率（如超过8K），否则不仅影响创建性能，生成的草稿文件也会占用大量存储空间，后续编辑极易出现卡顿。
• 并发控制：同一用户请勿同时保存同一草稿，否则容易引发数据覆盖和状态混乱。每次保存后，如果草稿不再使用，记得及时清除缓存中的数据。

错误码对照表