API 接口文档

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构概览
5. 详细组件分析
6. 双语文档
7. 依赖关系分析
8. 性能考虑
9. 故障排除指南
10. 小结

简介

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 再链式调用其他接口。