媒体处理接口
目录
简介
CapCut Mate 是基于 FastAPI 的媒体处理接口服务，用于与剪映（CapCut）集成，提供媒体素材添加和处理能力。系统支持视频、音频、图片、贴纸等多种媒体类型的批量处理，包含时间轴管理和轨道控制系统。
本项目为开发者提供标准化 API 接口，可将各种媒体素材集成到剪映项目中，实现自动化内容创作和视频编辑流程。
核心API接口
系统提供完整的 RESTful API 接口，所有接口遵循统一的命名规范和响应格式。主要接口包括：
- 草稿管理 :
/create_draft,/save_draft,/get_draft - 媒体添加 :
/add_videos,/add_audios,/add_images,/add_sticker - 视频生成 :
/gen_video,/gen_video_status
视频处理接口
接口定义
视频处理接口支持批量添加视频到剪映草稿，提供丰富的参数配置：
请求参数
draft_url: 草稿 URL（必需）video_infos: 视频信息数组（JSON 字符串，必需）alpha: 透明度（0-1，默认 1.0）scale_x/scale_y: 缩放比例（建议 0.1-5.0，默认 1.0）transform_x/y: 位置偏移（像素）
视频信息结构
json
{
"video_url": "https://example.com/video.mp4",
"width": 1920,
"height": 1080,
"start": 0,
"end": 10000000,
"duration": 10000000,
"mask": "",
"transition": "",
"transition_duration": 500000,
"volume": 1.0
}处理流程
有效
无效
有转场
无转场
开始处理
解析视频信息
验证参数
下载视频文件
返回错误
创建视频素材
创建视频片段
添加转场效果
应用转场
跳过转场
添加到轨道
保存草稿
返回结果
结束
音频处理接口
接口定义
音频处理接口支持批量添加音频到剪映草稿：
请求参数
draft_url: 草稿 URL（必需）audio_infos: 音频信息数组（JSON 字符串，必需）
音频信息结构
json
{
"audio_url": "https://example.com/audio.mp3",
"duration": 23184000,
"start": 0,
"end": 23184000
}处理流程
音频处理相对简单，主要涉及文件下载和轨道添加：
音频轨道 草稿引擎 下载器 服务层 API接口 音频轨道 草稿引擎 下载器 服务层 API接口 add_audios() 下载音频文件 返回本地路径 创建音频素材 添加到音频轨道 返回轨道信息 标准化响应
图片处理接口
接口定义
图片处理接口支持批量添加图片到剪映草稿：
请求参数
draft_url: 草稿 URL（必需）image_infos: 图片信息数组（JSON 字符串，必需）alpha: 透明度（0-1，默认 1.0）scale_x/scale_y: 缩放比例transform_x/y: 位置偏移（像素）
图片信息结构
json
{
"image_url": "https://example.com/image.png",
"width": 1920,
"height": 1080,
"start": 0,
"end": 5000000,
"duration": 5000000,
"animation": "淡入淡出",
"transition": "溶解",
"transition_duration": 500000
"alpha": 1.0
}贴纸处理接口
接口定义
贴纸处理接口支持在指定时间范围内添加贴纸到剪映草稿：
请求参数
draft_url: 草稿 URL（必需）sticker_id: 贴纸 ID（必需）start/end: 开始和结束时间（微秒，必需）scale: 缩放比例（0.1-5.0，默认 1.0）transform_x/y: 位置偏移（像素）
贴纸管理
系统提供贴纸搜索和管理功能：
"生成"
StickerRequest
+string draft_url
+string sticker_id
+integer start
+integer end
+float scale
+integer transform_x
+integer transform_y
StickerResponse
+string draft_url
+string sticker_id
+string track_id
+string segment_id
+integer duration
草稿管理接口
创建草稿
接口 : POST /v1/create_draft
请求参数
width: 视频宽度（默认 1920）height: 视频高度（默认 1080）
响应参数
draft_url: 草稿URLtip_url: 帮助文档URL
保存草稿
接口 : POST /v1/save_draft
请求参数
draft_url: 草稿URL
响应参数
draft_url: 保存后的草稿URL
获取草稿
接口 : GET /v1/get_draft
请求参数
draft_id: 草稿ID
响应参数
files: 文件列表
错误处理
常见错误类型
草稿相关错误
INVALID_DRAFT_URL: 草稿 URL 无效或已过期DRAFT_NOT_FOUND: 草稿文件不存在DRAFT_SAVE_FAILED: 草稿保存失败
媒体处理错误
VIDEO_ADD_FAILED: 视频添加失败AUDIO_ADD_FAILED: 音频添加失败IMAGE_ADD_FAILED: 图片添加失败STICKER_ADD_FAILED: 贴纸添加失败
调试建议
- 检查网络连接: 确保媒体文件 URL 可访问
- 验证文件格式: 确认媒体文件格式受支持
- 检查时间轴配置: 确保时间参数合理且不重叠
- 查看日志文件: 分析详细的错误信息和堆栈跟踪
最佳实践
性能优化
- 批量处理: 合理使用批量添加接口减少请求次数
- 缓存策略: 利用草稿缓存避免重复下载
- 资源复用: 在同一草稿中复用相同的媒体文件
- 并发控制: 控制同时处理的媒体数量
参数验证
- 时间参数: 确保 end > start
- 数值范围: 验证透明度、缩放等参数在允许范围内
- URL有效性: 确保媒体文件URL可访问
- 文件格式: 支持常见的视频、音频、图片格式
错误恢复
- 重试机制: 对于网络错误实现自动重试
- 降级策略: 当部分媒体处理失败时继续处理其他媒体
- 日志记录: 完善的错误日志便于问题排查
文档信息
- 接口文档： docs.jcaigc.cn
- 效果案例： www.jcaigc.cn/workflow
- 开源仓库： capcut-mate