AI 助理
文档备案控制台
开发者社区 阿里云百炼 文章 正文

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

2026-04-28 231
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： CapCut Mate 是基于 FastAPI 构建的剪映自动化 API，提供草稿管理、媒体添加、特效/字幕/贴纸应用、时间线计算及云端渲染等 RESTful 接口，遵循 OpenAPI 规范，支持中英文双语文档与完整错误处理。（239字）

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

文章标签：
大模型服务平台百炼
API
中间件
数据格式
JSON
前端开发
1575030468644753
目录
相关文章
1575030468644753
|
2月前
|
API Docker 容器
开源剪映小助手(capcut-mate)v3.0.26发布
CapCut Mate API 是开源免费的剪映草稿自动化工具，基于 FastAPI 构建，支持独立部署。赋能大模型实现智能视频剪辑，覆盖剪映核心功能全流程，可对接 Coze/n8n 或云渲染生成成品视频。Docker 三行命令极速部署，文档更清晰简洁。（239字）
1575030468644753
788 5
1575030468644753
|
2月前
|
API
开源剪映小助手(capcut-mate)v3.0.22发布
CapCut Mate API 是开源免费的剪映草稿自动化工具，基于 FastAPI，支持独立部署。为大模型提供开箱即用的视频编辑 Skills，实现剪映核心功能全流程自动化，轻松生成专业视频。兼容 Coze/n8n，支持云渲染。
1575030468644753
1033 1
1575030468644753
|
18天前
|
存储 人工智能 中间件
【开源剪映小助手】项目介绍
CapCut Mate API 是一款开源免费的剪映自动化工具，基于 FastAPI 构建，支持本地/云端部署。深度集成大模型，实现草稿创建、智能剪辑、云端渲染等全流程自动化，可无缝对接 Coze/n8n，赋能个人创作者、企业及教育机构高效产出专业视频。（239字）
1575030468644753
329 0
1575030468644753
|
28天前
|
存储 缓存 数据库
【开源剪映小助手】核心功能详解
CapCut Mate 是基于 Python 的剪映自动化工具，通过 FastAPI 提供 RESTful 接口，支持草稿管理、媒体处理、效果编辑与视频生成全流程自动化。采用分层模块化架构，具备双文件模板兼容、智能缓存、异步渲染及完善故障排查能力。（239字）
1575030468644753
224 4
1575030468644753
|
2月前
|
前端开发 中间件 API
【剪映小助手】快速开始
capcut-mate 是面向剪映的自动化辅助工具，提供草稿管理、媒体处理、字幕特效及视频生成能力，支持 OpenAPI 与桌面客户端。新增中英文双语支持、智能语言切换（基于 Accept-Language）、跨平台适配（Windows/Linux）及统一响应格式，开箱即用。
1575030468644753
879 6
1575030468644753
|
25天前
|
监控 Linux API
【开源剪映小助手】视频生成流程
本项目是基于剪映专业版自动化控制的云端视频生成系统，支持草稿创建、素材添加、渲染导出、状态查询与结果下载全流程。采用异步任务队列与三层架构，具备Windows/Linux/macOS跨平台兼容性，并在非Windows环境提供优雅降级机制。（239字）
1575030468644753
207 2
bailiantest1
|
4月前
|
消息中间件 人工智能 自然语言处理
阿里云百炼产品月报【2025年12月】
阿里云百炼重磅升级：支持多模态文件上传与智能解析，MCP体验优化并新增12个云部署服务，知识库交互重构，上线146个应用模板及24款新模型，全面赋能AI应用开发。
bailiantest1
1000 3
1575030468644753
|
19天前
|
Linux 测试技术 开发者
【开源剪映小助手】开发者指南
capcut-mate 是开源剪映自动化工具，基于 FastAPI + Electron 构建，支持跨平台草稿管理、媒体处理与视频导出。采用分层架构、条件依赖与优雅降级机制，确保 Windows/Linux 兼容性与一致开发体验。（239字）
1575030468644753
206 3
1575030468644753
|
21天前
|
监控 前端开发 中间件
【开源剪映小助手】调试与故障排除
本指南面向capcut-mate开发者，系统梳理Python后端（FastAPI）、Electron桌面端与React前端的调试方法，涵盖日志分析、IPC通信、异常处理、性能优化及常见故障排查，助力高效定位与解决运行时问题。（239字）
1575030468644753
110 10

阿里云百炼

热门文章

最新文章

  • 1
    阿里云百炼上线DeepSeek-V4：API 价格与官网一致，百万Tokens输入最低1元、输出最低2元
  • 2
    数据中心网络带宽线速有门道
  • 3
    阿里云百炼官网登录入口：首页和后台API管理调用控制台
  • 4
    阿里云百炼 API 调用教程：准备 API-Key、配置环境变量和调用 API 流程
  • 5
    【SpringAIAlibaba新手村系列】（1）初识 Spring AI Alibaba 框架
  • 6
    从零搭建企业私有知识库：RAG + 大模型实战（附完整代码）
  • 7
    阿里云百炼平台介绍：官网入口链接、免费AI大模型领取及常见问题解答FAQ
  • 8
    阿里云百炼Coding Plan产品简介：支持模型、收费标准及购买和使用常见问题解答
  • 9
    Qoder：面向真实软件的智能体编程平台，让AI从“助手”变为“协同开发者
  • 10
    阿里云百炼Token Plan与Coding Plan怎么选？支持模型、适配AI工具与收费模式对比
  • 1
    Qoder 1.0正式发布！从AI IDE迈向智能体自主开发工作台
    140
  • 2
    阿里云Coding Plan介绍：支持模型与AI工具、套餐价格标准、使用步骤参考
    50
  • 3
    OpenClaw、Hermes Agent、Claude Code 接入配置阿里云百炼大模型保姆级教程
    73
  • 4
    阿里云Token Plan 团队版介绍：支持模型与AI工具、套餐收费价格标准、使用步骤参考
    50
  • 5
    Hermes和OpenClaw有什么区别？如何选择？使用阿里云轻量应用服务器部署流程简介
    48
  • 6
    【剪映小助手】音频信息生成接口
    24
  • 7
    阿里云百炼DeepSeek-V4-Pro/Flash全量上线：计费标准、折扣政策与场景化应用详解
    147
  • 8
    阿里云百炼API-Key完整获取教程：从零到一键调用全流程及常见问题解答
    75
  • 9
    阿里云大模型服务平台怎么用？模型训练、模型部署计费规则及价格参考
    42
  • 10
    阿里云 OpenClaw（Clawdbot）一键部署、配置阿里云百炼 Token Plan API 图文教程
    51

    • 相关电子书

    更多
  • 低代码开发师（初级）实战教程
  • 冬季实战营第三期：MySQL数据库进阶实战
  • 阿里巴巴DevOps 最佳实践手册
    • 下一篇
    阿里云重磅新品：Agent安全中心，全新安全框架下AI Agent一体化防御平台