添加关键帧接口
目录
简介
添加关键帧接口：说明该接口在草稿自动化里的用途、依赖模块与常见报错。具体方法、路径、字段和校验请以 OpenAPI 为准。
依赖关系分析
系统各组件之间的依赖关系清晰，遵循单一职责原则：
graph TB
subgraph "外部依赖"
FastAPI[FastAPI 框架]
Pydantic[Pydantic 数据验证]
UUID[UUID 生成]
end
subgraph "内部模块"
Router[路由模块]
Service[服务模块]
Schema[数据模型]
Keyframe[关键帧引擎]
Cache[缓存管理]
Exceptions[异常处理]
end
subgraph "工具模块"
Logger[日志记录]
Helper[辅助函数]
Media[媒体处理]
end
FastAPI --> Router
Pydantic --> Schema
UUID --> Keyframe
Router --> Service
Service --> Schema
Service --> Keyframe
Service --> Cache
Service --> Exceptions
Service --> Logger
Service --> Helper
Service --> Media
错误处理机制
系统采用统一的异常处理机制，提供详细的错误信息：
| 错误码 | 中文描述 | 英文描述 | 解决方案 |
|---|---|---|---|
| 2001 | 无效的草稿URL | Invalid draft URL | 检查草稿URL是否正确 |
| 2013 | 无效的关键帧信息，请检查keyframes字段值是否正确 | Invalid keyframe information | 检查关键帧数据格式 |
| 2014 | 关键帧添加失败 | Keyframe addition failed | 联系技术支持 |
| 2015 | 片段未找到，请检查segment_id是否正确 | Segment not found | 确认片段ID是否正确 |
| 2016 | 无效的片段类型，该片段不支持关键帧 | Invalid segment type | 确保为目标片段是视觉片段 |
| 2017 | 无效的关键帧属性类型 | Invalid keyframe property type | 检查属性类型是否在支持列表中 |
性能考虑
缓存策略
- LRU缓存: 最大缓存10000个草稿实例
- 内存管理: 自动清理最久未使用的草稿
- 并发访问: 支持多线程安全访问
数据处理优化
- 批量处理: 支持一次添加多个关键帧
- 增量更新: 只保存修改后的草稿
- 错误容忍: 单个关键帧失败不影响整体操作
性能建议
- 批量操作: 建议单次请求不超过100个关键帧
- 缓存复用: 复用同一个草稿URL进行多次操作
- 合理分页: 对于大量关键帧，建议分批处理
故障排除指南
常见问题及解决方案
1. 草稿URL无效
症状: 返回404错误
原因: 草稿URL格式不正确或草稿不存在
解决方案:
- 确保使用正确的草稿URL格式
- 验证草稿URL是否在有效期内
- 检查草稿ID是否正确
2. 关键帧数据格式错误
症状: 返回400错误，错误信息为"无效的关键帧信息"
原因: JSON数据格式不正确或缺少必填字段
解决方案:
- 确保keyframes参数为有效的JSON字符串
- 检查每个关键帧对象是否包含segment_id、property、offset、value字段
- 验证offset必须为非负数
3. 片段类型不支持
症状: 返回400错误，错误信息为"无效的片段类型"
原因: 目标片段不是视觉片段
解决方案:
- 确保目标片段为视频、图片、贴纸或文本片段
- 检查segment_id是否正确
4. 属性类型不支持
症状: 返回400错误，错误信息为"无效的关键帧属性类型"
原因: property字段值不在支持列表中
解决方案:
- 检查属性类型是否在支持列表中
- 确保属性类型字符串拼写正确
调试技巧
- 启用详细日志: 在开发环境中开启详细日志记录
- 分步调试: 将复杂操作拆分为简单步骤
- 单元测试: 为关键帧添加功能编写单元测试
- 性能监控: 监控关键帧添加的性能指标
更多信息
字段说明、校验规则与示例以 OpenAPI 为准；需要对照源码时请查看 schemas/、service/ 与路由注册处。
