视频信息生成接口
目录
项目简介
CapCut Mate API 是一个基于 FastAPI 的开源剪映自动化助手，专注于为大模型提供基础的视频编辑能力。该项目完全开源免费，支持独立部署，可以与大型模型连接实现智能视频编辑。
主要特性
- 草稿管理：创建草稿、获取草稿、保存草稿
- 素材添加：添加视频、音频、图片、贴纸、字幕、效果、遮罩等
- 高级功能：关键帧控制、文本样式、动画效果等
- 视频导出：云端渲染生成最终视频
- 数据验证：使用 Pydantic 进行请求数据验证
- RESTful API：符合标准 API 设计规范
- 自动文档：FastAPI 自动生成交互式 API 文档
技术栈
- Python 3.11+
- FastAPI：高性能 Web 框架
- Pydantic：数据验证和模型定义
- Passlib：密码加密（如使用用户认证）
- Uvicorn：ASGI 服务器
- uv：Python 包管理和项目管理工具
依赖关系分析
graph TB
subgraph "外部依赖"
FastAPI[FastAPI]
Pydantic[Pydantic]
Uvicorn[Uvicorn]
Requests[Requests]
Subprocess[Subprocess]
end
subgraph "内部模块"
Router[路由模块]
Service[服务模块]
Schema[数据模型]
Utils[工具模块]
Middleware[中间件]
end
subgraph "剪映集成"
VideoSegment[视频片段]
ScriptFile[脚本文件]
DraftDownloader[草稿下载器]
end
FastAPI --> Router
Pydantic --> Schema
Router --> Service
Service --> Utils
Service --> VideoSegment
Utils --> DraftDownloader
Utils --> Requests
Utils --> Subprocess
Middleware --> Router
VideoSegment --> ScriptFile
核心依赖关系
classDiagram
class MainApplication {
+FastAPI app
+include_router()
+add_middleware()
+run_server()
}
class APIRouter {
+register_routes()
+handle_requests()
}
class VideoInfosService {
+validate_input()
+process_request()
+generate_response()
}
class MediaUtils {
+get_duration()
+download_file()
+process_media()
}
MainApplication --> APIRouter : "包含"
APIRouter --> VideoInfosService : "调用"
VideoInfosService --> MediaUtils : "使用"
性能考虑
并发处理
项目采用异步处理机制，支持高并发请求处理：
- 异步路由：FastAPI 原生支持异步路由处理
- 连接池：数据库连接和 HTTP 请求使用连接池管理
- 缓存策略：频繁访问的媒体信息可以使用缓存减少重复计算
资源管理
flowchart TD
A[请求到达] --> B[参数验证]
B --> C[检查缓存]
C --> D{缓存命中?}
D --> |是| E[直接返回缓存]
D --> |否| F[执行业务逻辑]
F --> G[生成响应]
G --> H[写入缓存]
H --> I[返回响应]
E --> I
内存优化
- 流式处理：大文件下载采用流式处理，避免内存溢出
- 分块传输：支持大文件的分块上传和下载
- 垃圾回收：及时释放不需要的对象引用
故障排除指南
常见错误类型
| 错误代码 | 错误信息 | 描述 | 解决方案 |
|---|---|---|---|
| 400 | video_urls is required | 缺少视频 URL 参数 | 提供有效的视频 URL 数组 |
| 400 | timelines is required | 缺少时间线参数 | 提供有效的时间线数组 |
| 400 | Array length mismatch | video_urls 和 timelines 数组长度不匹配 | 确保两个数组具有相同的长度 |
| 400 | Invalid volume value | 音量值不在 0.0-2.0 范围内 | 使用 0.0-2.0 之间的音量值 |
| 404 | Video resource not found | 视频 URL 无法访问 | 检查视频 URL 是否可访问 |
| 500 | Video information generation failed | 内部处理错误 | 联系技术支持 |
调试技巧
- 启用详细日志：在开发环境中启用详细日志输出
- 参数验证：使用 Pydantic 的参数验证功能
- 单元测试：编写完整的单元测试覆盖边界情况
- 监控指标：添加性能监控和错误统计
环境配置
flowchart TD
A[启动应用] --> B[加载配置]
B --> C[检查依赖]
C --> D{依赖检查}
D --> |通过| E[初始化数据库]
D --> |失败| F[错误处理]
E --> G[启动服务器]
G --> H[监听端口]
F --> I[退出进程]
更多信息
字段说明、校验规则与示例以 OpenAPI 为准；需要对照源码时请查看 schemas/、service/ 与路由注册处。
