【开源剪映小助手】添加特效接口（Add Effects）

添加特效接口

简介

添加特效接口：说明该接口在草稿自动化里的用途、依赖模块与常见报错。具体方法、路径、字段和校验请以 OpenAPI 为准。

依赖关系分析

系统各组件之间的依赖关系呈现清晰的层次结构：
#mermaid-svg-bLfwpz6Yi4nARnpm{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-bLfwpz6Yi4nARnpm .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-bLfwpz6Yi4nARnpm .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-bLfwpz6Yi4nARnpm .error-icon{fill:#552222;}#mermaid-svg-bLfwpz6Yi4nARnpm .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-bLfwpz6Yi4nARnpm .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-bLfwpz6Yi4nARnpm .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-bLfwpz6Yi4nARnpm .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-bLfwpz6Yi4nARnpm .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-bLfwpz6Yi4nARnpm .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-bLfwpz6Yi4nARnpm .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-bLfwpz6Yi4nARnpm .marker{fill:#333333;stroke:#333333;}#mermaid-svg-bLfwpz6Yi4nARnpm .marker.cross{stroke:#333333;}#mermaid-svg-bLfwpz6Yi4nARnpm svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-bLfwpz6Yi4nARnpm p{margin:0;}#mermaid-svg-bLfwpz6Yi4nARnpm .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-bLfwpz6Yi4nARnpm .cluster-label text{fill:#333;}#mermaid-svg-bLfwpz6Yi4nARnpm .cluster-label span{color:#333;}#mermaid-svg-bLfwpz6Yi4nARnpm .cluster-label span p{background-color:transparent;}#mermaid-svg-bLfwpz6Yi4nARnpm .label text,#mermaid-svg-bLfwpz6Yi4nARnpm span{fill:#333;color:#333;}#mermaid-svg-bLfwpz6Yi4nARnpm .node rect,#mermaid-svg-bLfwpz6Yi4nARnpm .node circle,#mermaid-svg-bLfwpz6Yi4nARnpm .node ellipse,#mermaid-svg-bLfwpz6Yi4nARnpm .node polygon,#mermaid-svg-bLfwpz6Yi4nARnpm .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-bLfwpz6Yi4nARnpm .rough-node .label text,#mermaid-svg-bLfwpz6Yi4nARnpm .node .label text,#mermaid-svg-bLfwpz6Yi4nARnpm .image-shape .label,#mermaid-svg-bLfwpz6Yi4nARnpm .icon-shape .label{text-anchor:middle;}#mermaid-svg-bLfwpz6Yi4nARnpm .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-bLfwpz6Yi4nARnpm .rough-node .label,#mermaid-svg-bLfwpz6Yi4nARnpm .node .label,#mermaid-svg-bLfwpz6Yi4nARnpm .image-shape .label,#mermaid-svg-bLfwpz6Yi4nARnpm .icon-shape .label{text-align:center;}#mermaid-svg-bLfwpz6Yi4nARnpm .node.clickable{cursor:pointer;}#mermaid-svg-bLfwpz6Yi4nARnpm .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-bLfwpz6Yi4nARnpm .arrowheadPath{fill:#333333;}#mermaid-svg-bLfwpz6Yi4nARnpm .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-bLfwpz6Yi4nARnpm .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-bLfwpz6Yi4nARnpm .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bLfwpz6Yi4nARnpm .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-bLfwpz6Yi4nARnpm .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bLfwpz6Yi4nARnpm .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-bLfwpz6Yi4nARnpm .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-bLfwpz6Yi4nARnpm .cluster text{fill:#333;}#mermaid-svg-bLfwpz6Yi4nARnpm .cluster span{color:#333;}#mermaid-svg-bLfwpz6Yi4nARnpm 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-bLfwpz6Yi4nARnpm .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-bLfwpz6Yi4nARnpm rect.text{fill:none;stroke-width:0;}#mermaid-svg-bLfwpz6Yi4nARnpm .icon-shape,#mermaid-svg-bLfwpz6Yi4nARnpm .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bLfwpz6Yi4nARnpm .icon-shape p,#mermaid-svg-bLfwpz6Yi4nARnpm .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-bLfwpz6Yi4nARnpm .icon-shape .label rect,#mermaid-svg-bLfwpz6Yi4nARnpm .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bLfwpz6Yi4nARnpm .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-bLfwpz6Yi4nARnpm .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-bLfwpz6Yi4nARnpm :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 剪映集成
内部模块
核心模块
外部依赖
FastAPI框架
数据验证
HTTP客户端
路由模块
服务模块
数据模型
工具模块
草稿缓存
特效元数据
辅助工具
异常处理
草稿文件
特效片段
轨道管理

性能考虑

系统在设计时充分考虑了性能优化：

缓存策略：采用 LRU 缓存管理草稿实例，限制最大缓存大小为 10000 个
异步处理：利用 FastAPI 的异步特性提高并发处理能力
内存管理：及时清理不再使用的草稿实例，避免内存泄漏
批量处理：支持批量特效添加，减少 API 调用次数

故障排除指南

常见错误及解决方案

错误代码	错误信息	可能原因	解决方案
2001	无效的草稿URL	草稿URL格式不正确或草稿不存在	检查草稿URL格式，确认草稿ID有效
2020	无效的特效信息	特效参数格式错误或缺失	验证effect_infos字段格式，确保必填参数齐全
2021	特效添加失败	特效创建或添加过程中发生错误	检查特效名称是否正确，确认特效可用性
2022	特效未找到	指定的特效名称不存在	确认特效名称与系统支持的特效列表一致

调试建议

启用详细日志：查看服务端日志了解详细的错误信息
参数验证：确保所有必填参数都已正确提供
网络连接：确认与剪映引擎的连接正常
权限检查：验证API访问权限和认证信息

文档信息

接口文档： docs.jcaigc.cn
效果案例： www.jcaigc.cn/workflow
开源仓库： capcut-mate