添加特效接口
目录
简介
添加特效接口：说明该接口在草稿自动化里的用途、依赖模块与常见报错。具体方法、路径、字段和校验请以 OpenAPI 为准。
依赖关系分析
系统各组件之间的依赖关系呈现清晰的层次结构：
graph TD
subgraph "外部依赖"
FastAPI[FastAPI框架]
Pydantic[数据验证]
Requests[HTTP客户端]
end
subgraph "核心模块"
Router[路由模块]
Service[服务模块]
Schema[数据模型]
Utils[工具模块]
end
subgraph "内部模块"
DraftCache[草稿缓存]
EffectMeta[特效元数据]
Helper[辅助工具]
Exceptions[异常处理]
end
subgraph "剪映集成"
ScriptFile[草稿文件]
EffectSegment[特效片段]
Track[轨道管理]
end
FastAPI --> Router
Pydantic --> Schema
Requests --> Utils
Router --> Service
Service --> DraftCache
Service --> EffectMeta
Service --> Helper
Service --> Exceptions
DraftCache --> ScriptFile
EffectMeta --> EffectSegment
ScriptFile --> Track
EffectSegment --> Track
性能考虑
系统在设计时充分考虑了性能优化：
- 缓存策略：采用 LRU 缓存管理草稿实例，限制最大缓存大小为 10000 个
- 异步处理：利用 FastAPI 的异步特性提高并发处理能力
- 内存管理：及时清理不再使用的草稿实例，避免内存泄漏
- 批量处理：支持批量特效添加，减少 API 调用次数
故障排除指南
常见错误及解决方案
| 错误代码 | 错误信息 | 可能原因 | 解决方案 |
|---|---|---|---|
| 2001 | 无效的草稿URL | 草稿URL格式不正确或草稿不存在 | 检查草稿URL格式，确认草稿ID有效 |
| 2020 | 无效的特效信息 | 特效参数格式错误或缺失 | 验证effect_infos字段格式，确保必填参数齐全 |
| 2021 | 特效添加失败 | 特效创建或添加过程中发生错误 | 检查特效名称是否正确，确认特效可用性 |
| 2022 | 特效未找到 | 指定的特效名称不存在 | 确认特效名称与系统支持的特效列表一致 |
调试建议
- 启用详细日志：查看服务端日志了解详细的错误信息
- 参数验证：确保所有必填参数都已正确提供
- 网络连接：确认与剪映引擎的连接正常
- 权限检查：验证API访问权限和认证信息
更多信息
字段说明、校验规则与示例以 OpenAPI 为准；需要对照源码时请查看 schemas/、service/ 与路由注册处。
