媒体处理接口
目录
简介
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: 位置偏移（像素）
视频信息结构
{
"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
}
处理流程
flowchart TD
Start([开始处理]) --> Parse[解析视频信息]
Parse --> Validate{验证参数}
Validate --> |有效| Download[下载视频文件]
Validate --> |无效| Error[返回错误]
Download --> CreateMaterial[创建视频素材]
CreateMaterial --> CreateSegment[创建视频片段]
CreateSegment --> AddTransition{添加转场效果}
AddTransition --> |有转场| ApplyTransition[应用转场]
AddTransition --> |无转场| SkipTransition[跳过转场]
ApplyTransition --> AddTrack[添加到轨道]
SkipTransition --> AddTrack
AddTrack --> SaveDraft[保存草稿]
SaveDraft --> Return[返回结果]
Error --> End([结束])
Return --> End
音频处理接口
接口定义
音频处理接口支持批量添加音频到剪映草稿：
请求参数
draft_url: 草稿 URL（必需）audio_infos: 音频信息数组（JSON 字符串，必需）
音频信息结构
{
"audio_url": "https://example.com/audio.mp3",
"duration": 23184000,
"start": 0,
"end": 23184000
}
处理流程
音频处理相对简单，主要涉及文件下载和轨道添加：
sequenceDiagram
participant API as API接口
participant Service as 服务层
participant Download as 下载器
participant Draft as 草稿引擎
participant Track as 音频轨道
API->>Service : add_audios()
Service->>Download : 下载音频文件
Download-->>Service : 返回本地路径
Service->>Draft : 创建音频素材
Service->>Track : 添加到音频轨道
Track-->>Service : 返回轨道信息
Service-->>API : 标准化响应
图片处理接口
接口定义
图片处理接口支持批量添加图片到剪映草稿：
请求参数
draft_url: 草稿 URL（必需）image_infos: 图片信息数组（JSON 字符串，必需）alpha: 透明度（0-1，默认 1.0）scale_x/scale_y: 缩放比例transform_x/y: 位置偏移（像素）
图片信息结构
{
"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: 位置偏移（像素）
贴纸管理
系统提供贴纸搜索和管理功能：
classDiagram
class StickerRequest {
+string draft_url
+string sticker_id
+integer start
+integer end
+float scale
+integer transform_x
+integer transform_y
}
class StickerResponse {
+string draft_url
+string sticker_id
+string track_id
+string segment_id
+integer duration
}
StickerRequest --> StickerResponse : "生成"
草稿管理接口
创建草稿
接口: 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可访问
- 文件格式: 支持常见的视频、音频、图片格式
错误恢复
- 重试机制: 对于网络错误实现自动重试
- 降级策略: 当部分媒体处理失败时继续处理其他媒体
- 日志记录: 完善的错误日志便于问题排查
