草稿管理接口

目录

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为正整数
  • 建议使用常见视频分辨率
• 调用顺序
  • 先调用创建草稿，再进行编辑操作
  • 频繁保存，避免中途断电或异常丢失
• 性能考虑
  • 避免超高分辨率导致性能问题
  • 高分辨率草稿占用更多存储空间
• 并发控制
  • 避免并发保存同一草稿
  • 保存后及时清理缓存中不再使用的草稿

错误码对照表