草稿管理接口

目录

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

简介

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

核心接口概览

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

接口详细说明

接口一：创建草稿

• 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：服务不可用

创建草稿工作流程

---

接口二：保存草稿

• HTTP方法与路径
  • POST /openapi/capcut-mate/v1/save_draft
• 功能描述
  • 将当前编辑状态持久化到磁盘，确保内容不丢失
  • 通常在完成编辑操作后调用
• 请求参数
  • draft_url：草稿URL，必填
• 响应字段
  • draft_url：保存后的草稿URL
• 错误处理
  • 400：缺少或格式无效的draft_url
  • 404：草稿不存在
  • 500：保存失败
  • 503：服务不可用

保存草稿工作流程

---

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

• HTTP方法与路径
  • GET /openapi/capcut-mate/v1/get_draft
• 功能描述
  • 获取指定草稿ID对应的所有文件列表
  • 用于草稿内容预览、文件管理和状态检查
• 请求参数
  • draft_id：字符串，必填，长度20-32
• 响应字段
  • files：文件URL列表（基于DOWNLOAD_URL拼接）
• 错误处理
  • 400：缺少或格式无效的draft_id
  • 404：草稿不存在
  • 500：获取失败
  • 503：服务不可用

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

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

错误码对照表

错误码	错误信息	描述	解决方案
400	width必须大于等于1	宽度参数非法	提供≥1的宽度值
400	height必须大于等于1	高度参数非法	提供≥1的高度值
400	参数类型错误	参数类型不正确	确保width和height为数值类型
400	draft_url是必需的	缺少draft_url参数	提供有效的draft_url
400	draft_id长度不在范围内	draft_id长度不符合要求	确保draft_id长度为20-32字符
404	草稿不存在	指定草稿无法找到	确认draft_url或draft_id正确性
500	草稿创建失败	内部服务错误	联系技术支持
500	保存失败	保存操作失败	联系技术支持或稍后重试
500	获取文件列表失败	获取文件列表失败	联系技术支持或稍后重试
503	服务不可用	系统维护	稍后重试

附录

• 接口文档： docs.jcaigc.cn
• 效果案例： www.jcaigc.cn/workflow
• 开源仓库： capcut-mate