Easy Create Material Api
目录
简介
快速创建素材接口：用于 CapCut Mate 草稿自动化。下文概括依赖、性能相关注意点与排错；字段与校验以 OpenAPI 为准。
依赖关系分析
组件间依赖关系
Easy Create Material API 的依赖关系体现了清晰的分层架构：
graph TD
subgraph "外部依赖"
FastAPI[FastAPI框架]
Pydantic[Pydantic模型验证]
Requests[HTTP请求库]
FFmpeg[媒体处理工具]
end
subgraph "核心组件"
Router[v1.py 路由]
Service[EasyCreateMaterial服务]
Schema[数据模型]
end
subgraph "基础设施"
Helper[工具函数]
Cache[LRU缓存]
Logger[日志记录]
Media[媒体处理]
Download[下载管理]
end
subgraph "剪映集成"
DraftEngine[草稿引擎]
MediaTypes[媒体类型处理]
Config[配置管理]
end
FastAPI --> Router
Pydantic --> Schema
Router --> Service
Service --> Helper
Service --> Cache
Service --> DraftEngine
Service --> Media
Service --> Download
Helper --> MediaTypes
Cache --> DraftEngine
Logger --> Service
Media --> FFmpeg
Download --> Requests
关键依赖组件
草稿缓存系统
系统使用 LRU（Least Recently Used）缓存机制来管理草稿实例，限制最大缓存数量为10000个，提高内存使用效率。
URL 参数解析
通过 helper.get_url_param 函数从草稿URL中提取 draft_id 参数，确保草稿的有效性和可访问性。
颜色转换机制
提供十六进制颜色代码到RGB值的转换功能，支持错误处理和默认值回退机制。
新增了媒体处理工具，通过 ffprobe 工具获取媒体文件的精确时长信息，提高了音频时长解析的准确性。
性能考虑
缓存策略
系统采用 LRU 缓存策略来优化草稿访问性能：
- 最大缓存容量：10000个草稿实例
- 自动清理策略：当缓存满时自动删除最久未使用的项
- 内存管理：使用 OrderedDict 实现高效的缓存更新和删除操作
异步处理
虽然当前实现为同步处理，但系统架构支持未来扩展为异步处理模式，以提高并发处理能力。
资源管理
- 内存使用: 通过缓存机制减少重复创建草稿实例的内存开销
- 网络请求: 优化媒体文件下载和处理流程，避免不必要的网络请求
- 磁盘I/O: 合理安排草稿保存时机，减少频繁的磁盘写入操作
- 资源目录: 建立规范的资源文件夹结构，避免文件混乱和重复
新增了媒体文件时长获取的性能优化，通过 ffprobe 工具获取精确的媒体时长信息，避免了不必要的文件解析开销。
故障排除指南
常见错误类型
草稿URL验证失败
错误表现: 返回 400 或 404 错误
可能原因:
- 草稿URL格式不正确
- 草稿ID不存在或已过期
- 草稿缓存中没有对应的草稿实例
解决方案:
- 验证草稿URL的完整性和正确性
- 确认草稿ID的有效性
- 检查草稿缓存状态
音频URL验证失败
错误表现: 返回 400 错误
可能原因:
- 音频URL为空或为 "null"
- 音频文件不可访问
- 不支持的音频格式
解决方案:
- 确保提供有效的音频URL
- 验证音频文件的可访问性
- 检查音频格式的兼容性
素材添加失败
错误表现: 返回 500 错误
可能原因:
- 媒体文件处理过程中发生异常
- 草稿引擎操作失败
- 磁盘空间不足
解决方案:
- 检查媒体文件的完整性和可用性
- 验证草稿引擎的状态
- 确认系统有足够的磁盘空间
调试建议
- 启用详细日志: 在开发环境中启用详细的日志记录，跟踪每个处理步骤
- 参数验证: 在请求发送前进行参数验证，确保所有必需参数都已提供
- 错误重试: 对于临时性错误（如网络超时），实现适当的重试机制
- 监控指标: 添加性能监控指标，跟踪接口的响应时间和成功率
新增了媒体文件时长获取的调试建议，包括 ffprobe 工具的使用和错误处理机制。
See also
Request/response fields and validation rules are defined in OpenAPI. For implementation details, see schemas/, service/, and the v1 router.
