# 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 提供接口定义、参数说明与示例，便于集成与测试
 - 部分接口另有中文说明文档，便于对照阅读

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

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

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

```mermaid
graph TB
subgraph "表现层"
R["FastAPI 路由 src/router/v1.py"]
M["请求/响应模型 src/schemas/*.py"]
D["文档与 OpenAPI"]
end
subgraph "业务层"
S["服务层 service.*"]
end
subgraph "控制层"
J["剪映控制器 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 渲染和静态文件服务
- 循环依赖
 - 项目结构清晰，未发现循环依赖迹象

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

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

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

## 小结

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

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

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

后端

音视频

开发工具

CapCutMate提供基于FastAPI的RESTful API，支持剪映草稿管理、视频生成等功能。包含草稿创建、媒体添加、特效应用、字幕处理等核心接口，采用三层架构设计，提供OpenAPI规范文档和中文说明，便于开发者集成使用。

媒体处理

中间件

路由

JSON

2026采购季 | AI焕新·智启新局

message-queue-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【开源剪映小助手】API 接口文档-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐