【开源剪映小助手】草稿管理接口

草稿管理接口

目录

1. 简介
2. 核心接口概览
3. 接口详细说明
4. 草稿URL生成规则
5. 文件结构说明
6. 最佳实践
7. 错误码对照表

简介

本文档详细介绍剪映草稿管理的核心API接口，包括创建草稿、保存草稿、获取草稿文件列表三个基础功能。文档涵盖每个接口的HTTP方法、URL路径、请求参数、响应格式、错误处理等关键信息，帮助开发者快速集成草稿管理系统。

核心接口概览

草稿管理接口遵循RESTful设计原则，提供简洁明了的三个核心API：

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

接口详细说明

接口一：创建草稿

• HTTP方法与路径

  • POST /openapi/capcut-mate/v1/create_draft

• 功能描述

  • 基于模板初始化剪映草稿项目，支持自定义画布宽高
  • 返回草稿URL和帮助文档URL

• 请求参数

  • width：数字，≥1，默认1920
  • height：数字，≥1，默认1080

• 响应字段

  • draft_url：草稿URL，形如".../get_draft?draft_id=2025..."
  • tip_url：帮助文档URL

• 错误处理

  • 400：参数类型错误或越界
  • 500：内部错误
  • 503：服务不可用

创建草稿工作流程

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

接口二：保存草稿

• HTTP方法与路径

  • POST /openapi/capcut-mate/v1/save_draft

• 功能描述

  • 将当前编辑状态持久化到磁盘，确保内容不丢失
  • 通常在完成编辑操作后调用

• 请求参数

  • draft_url：草稿URL，必填

• 响应字段

  • draft_url：保存后的草稿URL

• 错误处理

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

保存草稿工作流程

flowchart TD
Start(["开始"]) --> ParseURL["解析 draft_url 获取 draft_id"]
ParseURL --> CheckCache{"缓存中存在？"}
CheckCache --> |否| ErrNotFound["返回404 草稿不存在"]
CheckCache --> |是| Load["从缓存加载草稿对象"]
Load --> Save["调用 save() 持久化"]
Save --> 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 TD
Start(["开始"]) --> ValidateID["校验 draft_id 非空且长度20-32"]
ValidateID --> Exists{"草稿目录存在？"}
Exists --> |否| ErrNotFound["返回404 草稿不存在"]
Exists --> |是| Scan["遍历草稿目录获取文件列表"]
Scan --> BuildURL["批量生成下载URL"]
BuildURL --> Done(["结束"])
ErrNotFound --> Done

草稿URL生成规则

• 生成方式

  • 基于配置中的DRAFT_URL，附加query参数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为正整数
  • 建议使用常见视频分辨率

• 调用顺序

  • 先调用创建草稿，再进行编辑操作
  • 频繁保存，避免中途断电或异常丢失

• 性能考虑

  • 避免超高分辨率导致性能问题
  • 高分辨率草稿占用更多存储空间

• 并发控制

  • 避免并发保存同一草稿
  • 保存后及时清理缓存中不再使用的草稿

错误码对照表