添加关键帧接口
目录
简介
添加关键帧接口：说明该接口在草稿自动化里的用途、依赖模块与常见报错。具体方法、路径、字段和校验请以 OpenAPI 为准。
依赖关系分析
系统各组件之间的依赖关系清晰，遵循单一职责原则：
#mermaid-svg-pDSsfQeHstx06FEk{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-pDSsfQeHstx06FEk .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-pDSsfQeHstx06FEk .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-pDSsfQeHstx06FEk .error-icon{fill:#552222;}#mermaid-svg-pDSsfQeHstx06FEk .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-pDSsfQeHstx06FEk .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-pDSsfQeHstx06FEk .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-pDSsfQeHstx06FEk .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-pDSsfQeHstx06FEk .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-pDSsfQeHstx06FEk .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-pDSsfQeHstx06FEk .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-pDSsfQeHstx06FEk .marker{fill:#333333;stroke:#333333;}#mermaid-svg-pDSsfQeHstx06FEk .marker.cross{stroke:#333333;}#mermaid-svg-pDSsfQeHstx06FEk svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-pDSsfQeHstx06FEk p{margin:0;}#mermaid-svg-pDSsfQeHstx06FEk .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-pDSsfQeHstx06FEk .cluster-label text{fill:#333;}#mermaid-svg-pDSsfQeHstx06FEk .cluster-label span{color:#333;}#mermaid-svg-pDSsfQeHstx06FEk .cluster-label span p{background-color:transparent;}#mermaid-svg-pDSsfQeHstx06FEk .label text,#mermaid-svg-pDSsfQeHstx06FEk span{fill:#333;color:#333;}#mermaid-svg-pDSsfQeHstx06FEk .node rect,#mermaid-svg-pDSsfQeHstx06FEk .node circle,#mermaid-svg-pDSsfQeHstx06FEk .node ellipse,#mermaid-svg-pDSsfQeHstx06FEk .node polygon,#mermaid-svg-pDSsfQeHstx06FEk .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-pDSsfQeHstx06FEk .rough-node .label text,#mermaid-svg-pDSsfQeHstx06FEk .node .label text,#mermaid-svg-pDSsfQeHstx06FEk .image-shape .label,#mermaid-svg-pDSsfQeHstx06FEk .icon-shape .label{text-anchor:middle;}#mermaid-svg-pDSsfQeHstx06FEk .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-pDSsfQeHstx06FEk .rough-node .label,#mermaid-svg-pDSsfQeHstx06FEk .node .label,#mermaid-svg-pDSsfQeHstx06FEk .image-shape .label,#mermaid-svg-pDSsfQeHstx06FEk .icon-shape .label{text-align:center;}#mermaid-svg-pDSsfQeHstx06FEk .node.clickable{cursor:pointer;}#mermaid-svg-pDSsfQeHstx06FEk .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-pDSsfQeHstx06FEk .arrowheadPath{fill:#333333;}#mermaid-svg-pDSsfQeHstx06FEk .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-pDSsfQeHstx06FEk .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-pDSsfQeHstx06FEk .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-pDSsfQeHstx06FEk .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-pDSsfQeHstx06FEk .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-pDSsfQeHstx06FEk .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-pDSsfQeHstx06FEk .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-pDSsfQeHstx06FEk .cluster text{fill:#333;}#mermaid-svg-pDSsfQeHstx06FEk .cluster span{color:#333;}#mermaid-svg-pDSsfQeHstx06FEk div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-pDSsfQeHstx06FEk .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-pDSsfQeHstx06FEk rect.text{fill:none;stroke-width:0;}#mermaid-svg-pDSsfQeHstx06FEk .icon-shape,#mermaid-svg-pDSsfQeHstx06FEk .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-pDSsfQeHstx06FEk .icon-shape p,#mermaid-svg-pDSsfQeHstx06FEk .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-pDSsfQeHstx06FEk .icon-shape .label rect,#mermaid-svg-pDSsfQeHstx06FEk .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-pDSsfQeHstx06FEk .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-pDSsfQeHstx06FEk .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-pDSsfQeHstx06FEk :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 工具模块
内部模块
外部依赖
FastAPI 框架
Pydantic 数据验证
UUID 生成
路由模块
服务模块
数据模型
关键帧引擎
缓存管理
异常处理
日志记录
辅助函数
媒体处理
错误处理机制
系统采用统一的异常处理机制，提供详细的错误信息：
| 错误码 | 中文描述 | 英文描述 | 解决方案 |
|---|---|---|---|
| 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/ 与路由注册处。
文档信息
- 接口文档： docs.jcaigc.cn
- 效果案例： www.jcaigc.cn/workflow
- 开源仓库： capcut-mate