【开源剪映小助手】API 接口文档

API 接口文档

简介

CapCut Mate 提供 RESTful API，用于自动化剪映草稿管理与视频生成。API 基于 FastAPI 构建，遵循 OpenAPI 规范，支持草稿创建、媒体添加、特效与贴纸应用、字幕处理、时间线计算、素材信息生成以及云端渲染导出等功能。

项目结构

应用入口与路由挂载
- 应用入口文件负责创建 FastAPI 实例、注册路由与中间件，并启动服务
- 路由统一挂载在 /openapi/capcut-mate/v1 前缀下，便于版本化管理
路由与控制器
- v1 路由模块集中定义各业务接口，每个接口对应一个请求/响应模型与服务层调用
数据模型与校验
- 使用 Pydantic 模型定义请求参数与响应结构，内置字段级校验与默认值
文档与示例
- OpenAPI YAML 提供接口定义、参数说明与示例，便于集成与测试
- 部分接口另有中文说明文档，便于对照阅读

graph TB
A["应用入口<br/>main.py"] --> B["路由注册<br/>/openapi/capcut-mate/v1/*"]
B --> C["v1 路由模块<br/>src/router/v1.py"]
C --> D["请求模型<br/>src/schemas/*.py"]
C --> E["服务层调用<br/>service.*"]
E --> F["剪映控制<br/>JianyingController"]
G["中文文档<br/>docs/*.zh.md"] --> C
H["英文文档<br/>docs/*.md"] --> C

核心组件

应用入口与中间件
- 中间件顺序：PrepareMiddleware → ResponseMiddleware，确保请求预处理与统一响应格式
- 路由前缀：/openapi/capcut-mate/v1，标签：capcut-mate
路由模块
- v1 路由模块包含草稿管理、媒体处理、编辑效果、视频生成、工具类接口等
数据模型
- 请求/响应模型基于 Pydantic，内置类型、范围与默认值校验，减少重复校验逻辑
文档与示例
- OpenAPI YAML 提供接口定义、参数说明、示例与响应结构，便于客户端集成
- 中文文档版本，提供详细的中文接口说明与使用示例

架构概览

API 采用三层架构：

表现层：FastAPI 路由与请求/响应模型
业务层：服务层封装具体业务逻辑，如草稿创建、媒体添加、渲染导出等
控制层：与剪映交互，执行窗口激活、素材导入与渲染操作

graph TB
subgraph "表现层"
R["FastAPI 路由<br/>src/router/v1.py"]
M["请求/响应模型<br/>src/schemas/*.py"]
D["文档与 OpenAPI"]
end
subgraph "业务层"
S["服务层<br/>service.*"]
end
subgraph "控制层"
J["剪映控制器<br/>JianyingController"]
end
R --> M
R --> S
S --> J
D --> R

详细组件分析

草稿管理

创建草稿 (CREATE_DRAFT)

方法与路径：POST /openapi/capcut-mate/v1/create_draft
认证：无需认证
请求参数：
- width: 整数，最小值 1，示例：1920
- height: 整数，最小值 1，示例：1080
响应参数：
- draft_url: 字符串，草稿访问 URL
- tip_url: 字符串，帮助文档 URL
示例请求与响应：见 OpenAPI YAML 中的 create_draft 示例

保存草稿 (SAVE_DRAFT)

方法与路径：POST /openapi/capcut-mate/v1/save_draft
请求参数：
- draft_url: 字符串，草稿 URL
响应参数：
- draft_url: 字符串，草稿 URL
- message: 字符串，操作结果消息

获取草稿文件列表 (GET_DRAFT)

方法与路径：GET /openapi/capcut-mate/v1/get_draft
查询参数：
- draft_id: 字符串，长度 20-32，示例：202511262111301f5fceff
响应参数：
- files: 字符串数组，文件路径列表

媒体处理

批量添加视频 (ADD_VIDEOS)

方法与路径：POST /openapi/capcut-mate/v1/add_videos
请求参数：
- draft_url: 字符串，草稿 URL
- video_infos: 字符串，JSON 数组，包含视频 URL、尺寸、时间线与转场等
- alpha: 浮点数，范围 [0,1]
- scale_x/scale_y: 浮点数，建议范围 [0.1,5.0]
- transform_x/transform_y: 整数，像素偏移
响应参数：
- draft_url: 字符串
- track_id: 字符串
- video_ids: 字符串数组
- segment_ids: 字符串数组

批量添加音频 (ADD_AUDIOS)

方法与路径：POST /openapi/capcut-mate/v1/add_audios
请求参数：
- draft_url: 字符串
- audio_infos: 字符串，JSON 数组，包含音频 URL、时长与时间线
响应参数：
- draft_url: 字符串
- track_id: 字符串
- audio_ids: 字符串数组

批量添加图片 (ADD_IMAGES)

方法与路径：POST /openapi/capcut-mate/v1/add_images
请求参数：
- draft_url: 字符串
- image_infos: 字符串，JSON 数组，包含图片 URL、尺寸、透明度与动画
- alpha/scale_x/scale_y: 浮点数
- transform_x/transform_y: 整数
响应参数：
- draft_url: 字符串
- track_id: 字符串
- image_ids: 字符串数组
- segment_ids: 字符串数组
- segment_infos: 片段信息数组（含 id/start/end）

编辑效果

添加贴纸 (ADD_STICKER)

方法与路径：POST /openapi/capcut-mate/v1/add_sticker
请求参数：
- draft_url: 字符串
- sticker_id: 字符串，贴纸 ID
- start/end: 整数，微秒时间戳
- scale: 浮点数，建议范围 [0.1,5.0]
- transform_x/transform_y: 整数，像素偏移
响应参数：
- draft_url: 字符串
- sticker_id: 字符串
- track_id: 字符串
- segment_id: 字符串
- duration: 整数，微秒

添加特效 (ADD_EFFECTS)

方法与路径：POST /openapi/capcut-mate/v1/add_effects
请求参数：
- draft_url: 字符串
- effect_infos: 字符串，JSON 数组，包含特效标题与时间线
响应参数：
- draft_url: 字符串
- track_id: 字符串
- effect_ids: 字符串数组
- segment_ids: 字符串数组

添加字幕 (ADD_CAPTIONS)

方法与路径：POST /openapi/capcut-mate/v1/add_captions
请求参数：
- draft_url: 字符串
- captions: 字符串，JSON 数组，包含字幕文本与时间线
- text_color/alignment/alpha/font_size 等样式参数
- transform_x/transform_y/scale_x/scale_y 等变换参数
- style_text/underline/italic/bold/has_shadow 等开关
- shadow_info: 阴影参数对象（当 has_shadow=true 时生效）
响应参数：
- draft_url: 字符串
- track_id: 字符串
- text_ids: 字符串数组
- segment_ids: 字符串数组
- segment_infos: 片段信息数组

视频生成

生成视频 (GEN_VIDEO)

方法与路径：POST /openapi/capcut-mate/v1/gen_video
请求参数：
- draft_url: 字符串，草稿 URL
- apiKey: 可选字符串，合法 UUID 格式
响应参数：
- message: 字符串，响应消息

查询视频生成任务状态 (GEN_VIDEO_STATUS)

方法与路径：POST /openapi/capcut-mate/v1/gen_video_status
请求参数：
- draft_url: 字符串，草稿 URL
响应参数：
- 任务状态信息（具体字段由服务层返回）

工具与素材

快速创建素材轨道 (EASY_CREATE_MATERIAL)

方法与路径：POST /openapi/capcut-mate/v1/easy_create_material
请求参数：
- draft_url: 字符串
- audio_url/text/img_url/video_url: 字符串
- text_color/font_size/text_transform_y: 样式参数
响应参数：
- draft_url: 字符串
- message: 字符串，操作结果消息

获取音频时长 (GET_AUDIO_DURATION)

方法与路径：POST /openapi/capcut-mate/v1/get_audio_duration
请求参数：
- mp3_url: 字符串，音频 URL
响应参数：
- duration: 整数，音频时长（微秒）
- message: 字符串，操作结果消息

获取文字动画 (GET_TEXT_ANIMATIONS)

方法与路径：POST /openapi/capcut-mate/v1/get_text_animations
请求参数：
- mode/type: 整数，动画模式与类型
响应参数：
- effects: 动画效果数组（包含名称、时长、图标等）

获取图片动画 (GET_IMAGE_ANIMATIONS)

方法与路径：POST /openapi/capcut-mate/v1/get_image_animations
请求参数：
- mode/type: 整数，动画模式与类型
响应参数：
- effects: 动画效果数组（包含名称、时长、图标等）

搜索贴纸 (SEARCH_STICKER)

方法与路径：POST /openapi/capcut-mate/v1/search_sticker
请求参数：
- keyword: 字符串，关键词
响应参数：
- data: 贴纸数据数组，包含贴纸信息、ID 与标题
- message: 字符串，操作结果消息

提取链接 (GET_URL)

方法与路径：POST /openapi/capcut-mate/v1/get_url
请求参数：
- output: 字符串，提取内容
响应参数：
- output: 字符串，提取结果
响应格式更简洁，专注于 output 字段的说明

字符串列表转对象 (STR_LIST_TO_OBJS)

方法与路径：POST /openapi/capcut-mate/v1/str_list_to_objs
请求参数：
- infos: 字符串数组
响应参数：
- infos: 对象数组，每个对象包含 output 字段

对象列表转字符串 (OBJS_TO_STR_LIST)

方法与路径：POST /openapi/capcut-mate/v1/objs_to_str_list
请求参数：
- outputs: 对象数组，每个对象包含 output 字段
响应参数：
- infos: 字符串数组
响应格式更简洁，专注于 infos 字段的说明

时间线与素材信息生成

时间线计算
- 方法与路径：POST /openapi/capcut-mate/v1/timelines
- 请求参数：
  - duration/num/start/type: 整数，时长、份数、起始与分配策略
- 响应参数：
  - timelines/all_timelines: 时间线数组
音频时间线
- 方法与路径：POST /openapi/capcut-mate/v1/audio_timelines
- 请求参数：
  - links: 字符串数组，音频 URL 列表
- 响应参数：
  - timelines/all_timelines: 时间线数组
音频/图片/字幕/视频信息生成
- 方法与路径：
  - /openapi/capcut-mate/v1/audio_infos
  - /openapi/capcut-mate/v1/imgs_infos
  - /openapi/capcut-mate/v1/caption_infos
  - /openapi/capcut-mate/v1/video_infos
- 请求参数：
  - mp3_urls/imgs/texts/video_urls: 列表
  - timelines: 时间线数组
  - 其他样式与动画参数（如 font_size、mask、transition 等）
- 响应参数：
  - infos: JSON 字符串，包含生成的媒体信息

参数验证规则与数据类型

类型与范围
- 整数：如 width/height、start/end、font_size 等，需满足最小值或范围要求
- 浮点数：如 alpha、scale_x/scale_y、volume 等，需满足范围限制
- 字符串：如 draft_url、sticker_id、keyword 等，需符合长度与格式要求
可选参数
- 多数样式与动画参数为可选，未提供时使用默认值
校验器
- apiKey 使用 UUID 校验器，非法格式将触发错误

错误处理与状态码

标准响应
- 成功：HTTP 200，包含 code/message/draft_url 等字段（部分接口省略 code/message）
校验错误
- 参数不符合类型或范围时，FastAPI 将返回 422 Unprocessable Entity
API 密钥错误
- apiKey 非合法 UUID 格式时，将返回校验错误
业务错误
- 由服务层抛出的异常将通过统一响应中间件转换为标准格式

调用示例与最佳实践

调用示例
- 所有接口的请求与响应示例可在 OpenAPI YAML 中查看，涵盖草稿创建、媒体添加、特效与贴纸应用、字幕处理、时间线计算与素材信息生成等场景
- 部分接口另有中文说明页，可对照阅读
最佳实践
- 使用草稿 URL 作为跨接口的上下文标识，避免重复创建草稿
- 批量添加媒体时，合理设置透明度与缩放比例，确保画面协调
- 使用时间线工具生成均匀或随机分割的时间段，提升素材组织效率
- 为字幕与特效设置合理的开始/结束时间，避免重叠冲突
- 使用统一响应中间件处理异常，便于前端统一处理错误

双语文档

仓库中许多接口提供中文说明（文件名常含 Zh 或与英文版成对），并与 OpenAPI 描述一致。
若文档与 OpenAPI 不一致，以 OpenAPI 与源码为准。

依赖关系分析

组件耦合
- 路由模块依赖请求/响应模型与服务层；服务层依赖剪映控制器进行底层操作
- 文档系统与路由模块相互独立，通过接口定义进行关联
外部依赖
- FastAPI 提供路由与请求/响应模型校验；剪映控制器负责窗口与素材交互
- 文档系统依赖 Markdown 渲染和静态文件服务
循环依赖
- 项目结构清晰，未发现循环依赖迹象

graph LR
V1["v1 路由<br/>src/router/v1.py"] --> Schemas["请求/响应模型<br/>src/schemas/*.py"]
V1 --> Service["服务层<br/>service.*"]
Service --> Jianying["剪映控制器<br/>JianyingController"]
Docs["接口文档<br/>Markdown / OpenAPI"] --> V1

性能考虑

请求批量化
- 批量添加视频/音频/图片/字幕可减少往返次数，提升整体效率
时间线计算
- 使用时间线工具提前规划素材分布，避免运行时动态计算带来的延迟
资源复用
- 合理设置透明度与缩放比例，减少不必要的渲染开销
异步渲染
- 视频生成采用异步任务，建议使用查询状态接口轮询进度

故障排除指南

无法连接剪映
- 确认剪映已安装并可被系统识别；检查窗口激活逻辑是否成功
参数校验失败
- 检查字段类型、范围与必填项；参考模型定义修正请求
API 密钥格式错误
- 确保 apiKey 为合法 UUID 格式，否则将触发校验错误
响应异常
- 查看统一响应中间件日志，定位服务层异常原因

小结

接口覆盖从草稿创建、素材与效果编辑到渲染与辅助工具。字段、示例与错误码以 OpenAPI 为准；集成时建议先跑通 create_draft 再链式调用其他接口。