添加遮罩接口
目录
简介
添加遮罩接口：说明该接口在草稿自动化里的用途、依赖模块与常见报错。具体方法、路径、字段和校验请以 OpenAPI 为准。
依赖关系分析
核心依赖关系
#mermaid-svg-OJwYvamaMcULCTop{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-OJwYvamaMcULCTop .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-OJwYvamaMcULCTop .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-OJwYvamaMcULCTop .error-icon{fill:#552222;}#mermaid-svg-OJwYvamaMcULCTop .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-OJwYvamaMcULCTop .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-OJwYvamaMcULCTop .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-OJwYvamaMcULCTop .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-OJwYvamaMcULCTop .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-OJwYvamaMcULCTop .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-OJwYvamaMcULCTop .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-OJwYvamaMcULCTop .marker{fill:#333333;stroke:#333333;}#mermaid-svg-OJwYvamaMcULCTop .marker.cross{stroke:#333333;}#mermaid-svg-OJwYvamaMcULCTop svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-OJwYvamaMcULCTop p{margin:0;}#mermaid-svg-OJwYvamaMcULCTop .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-OJwYvamaMcULCTop .cluster-label text{fill:#333;}#mermaid-svg-OJwYvamaMcULCTop .cluster-label span{color:#333;}#mermaid-svg-OJwYvamaMcULCTop .cluster-label span p{background-color:transparent;}#mermaid-svg-OJwYvamaMcULCTop .label text,#mermaid-svg-OJwYvamaMcULCTop span{fill:#333;color:#333;}#mermaid-svg-OJwYvamaMcULCTop .node rect,#mermaid-svg-OJwYvamaMcULCTop .node circle,#mermaid-svg-OJwYvamaMcULCTop .node ellipse,#mermaid-svg-OJwYvamaMcULCTop .node polygon,#mermaid-svg-OJwYvamaMcULCTop .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-OJwYvamaMcULCTop .rough-node .label text,#mermaid-svg-OJwYvamaMcULCTop .node .label text,#mermaid-svg-OJwYvamaMcULCTop .image-shape .label,#mermaid-svg-OJwYvamaMcULCTop .icon-shape .label{text-anchor:middle;}#mermaid-svg-OJwYvamaMcULCTop .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-OJwYvamaMcULCTop .rough-node .label,#mermaid-svg-OJwYvamaMcULCTop .node .label,#mermaid-svg-OJwYvamaMcULCTop .image-shape .label,#mermaid-svg-OJwYvamaMcULCTop .icon-shape .label{text-align:center;}#mermaid-svg-OJwYvamaMcULCTop .node.clickable{cursor:pointer;}#mermaid-svg-OJwYvamaMcULCTop .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-OJwYvamaMcULCTop .arrowheadPath{fill:#333333;}#mermaid-svg-OJwYvamaMcULCTop .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-OJwYvamaMcULCTop .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-OJwYvamaMcULCTop .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-OJwYvamaMcULCTop .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-OJwYvamaMcULCTop .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-OJwYvamaMcULCTop .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-OJwYvamaMcULCTop .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-OJwYvamaMcULCTop .cluster text{fill:#333;}#mermaid-svg-OJwYvamaMcULCTop .cluster span{color:#333;}#mermaid-svg-OJwYvamaMcULCTop 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-OJwYvamaMcULCTop .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-OJwYvamaMcULCTop rect.text{fill:none;stroke-width:0;}#mermaid-svg-OJwYvamaMcULCTop .icon-shape,#mermaid-svg-OJwYvamaMcULCTop .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-OJwYvamaMcULCTop .icon-shape p,#mermaid-svg-OJwYvamaMcULCTop .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-OJwYvamaMcULCTop .icon-shape .label rect,#mermaid-svg-OJwYvamaMcULCTop .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-OJwYvamaMcULCTop .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-OJwYvamaMcULCTop .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-OJwYvamaMcULCTop :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 内部模块
外部依赖
FastAPI框架
Pydantic模型
Uvicorn服务器
v1.py 路由
add_masks.py 服务
add_masks.py 模型
draft_cache.py 缓存
helper.py 工具
mask_meta.py 遮罩元数据
video_segment.py 视频片段
数据流依赖
#mermaid-svg-ahROET6SVfZklHqR{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-ahROET6SVfZklHqR .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-ahROET6SVfZklHqR .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-ahROET6SVfZklHqR .error-icon{fill:#552222;}#mermaid-svg-ahROET6SVfZklHqR .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-ahROET6SVfZklHqR .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-ahROET6SVfZklHqR .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-ahROET6SVfZklHqR .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-ahROET6SVfZklHqR .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-ahROET6SVfZklHqR .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-ahROET6SVfZklHqR .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-ahROET6SVfZklHqR .marker{fill:#333333;stroke:#333333;}#mermaid-svg-ahROET6SVfZklHqR .marker.cross{stroke:#333333;}#mermaid-svg-ahROET6SVfZklHqR svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-ahROET6SVfZklHqR p{margin:0;}#mermaid-svg-ahROET6SVfZklHqR .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-ahROET6SVfZklHqR .cluster-label text{fill:#333;}#mermaid-svg-ahROET6SVfZklHqR .cluster-label span{color:#333;}#mermaid-svg-ahROET6SVfZklHqR .cluster-label span p{background-color:transparent;}#mermaid-svg-ahROET6SVfZklHqR .label text,#mermaid-svg-ahROET6SVfZklHqR span{fill:#333;color:#333;}#mermaid-svg-ahROET6SVfZklHqR .node rect,#mermaid-svg-ahROET6SVfZklHqR .node circle,#mermaid-svg-ahROET6SVfZklHqR .node ellipse,#mermaid-svg-ahROET6SVfZklHqR .node polygon,#mermaid-svg-ahROET6SVfZklHqR .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-ahROET6SVfZklHqR .rough-node .label text,#mermaid-svg-ahROET6SVfZklHqR .node .label text,#mermaid-svg-ahROET6SVfZklHqR .image-shape .label,#mermaid-svg-ahROET6SVfZklHqR .icon-shape .label{text-anchor:middle;}#mermaid-svg-ahROET6SVfZklHqR .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-ahROET6SVfZklHqR .rough-node .label,#mermaid-svg-ahROET6SVfZklHqR .node .label,#mermaid-svg-ahROET6SVfZklHqR .image-shape .label,#mermaid-svg-ahROET6SVfZklHqR .icon-shape .label{text-align:center;}#mermaid-svg-ahROET6SVfZklHqR .node.clickable{cursor:pointer;}#mermaid-svg-ahROET6SVfZklHqR .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-ahROET6SVfZklHqR .arrowheadPath{fill:#333333;}#mermaid-svg-ahROET6SVfZklHqR .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-ahROET6SVfZklHqR .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-ahROET6SVfZklHqR .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ahROET6SVfZklHqR .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-ahROET6SVfZklHqR .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ahROET6SVfZklHqR .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-ahROET6SVfZklHqR .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-ahROET6SVfZklHqR .cluster text{fill:#333;}#mermaid-svg-ahROET6SVfZklHqR .cluster span{color:#333;}#mermaid-svg-ahROET6SVfZklHqR 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-ahROET6SVfZklHqR .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-ahROET6SVfZklHqR rect.text{fill:none;stroke-width:0;}#mermaid-svg-ahROET6SVfZklHqR .icon-shape,#mermaid-svg-ahROET6SVfZklHqR .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ahROET6SVfZklHqR .icon-shape p,#mermaid-svg-ahROET6SVfZklHqR .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-ahROET6SVfZklHqR .icon-shape .label rect,#mermaid-svg-ahROET6SVfZklHqR .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ahROET6SVfZklHqR .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-ahROET6SVfZklHqR .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-ahROET6SVfZklHqR :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} HTTP 请求
参数验证
草稿缓存查找
片段搜索
遮罩应用
草稿保存
HTTP 响应
错误处理
性能考虑
缓存策略
系统使用 LRU 缓存管理草稿实例，最大缓存容量为 10000 个草稿：
- 内存管理：自动清理最久未使用的草稿
- 性能优化：避免重复加载相同草稿
- 并发安全：使用 OrderedDict 确保线程安全
批量处理优化
- 批量操作：支持同时为多个片段添加遮罩
- 异步处理：每个片段独立处理，提高吞吐量
- 资源复用：同一草稿实例在批量处理中重复使用
内存使用优化
- 延迟加载：草稿文件按需加载到内存
- 及时释放：处理完成后及时释放内存资源
- 监控告警：缓存满载时自动清理最旧项
故障排除指南
常见问题诊断
草稿相关问题
| 问题症状 | 可能原因 | 解决方案 |
|---|---|---|
| 400 错误：无效的草稿URL | URL 格式不正确或缺少参数 | 检查 draft_url 格式，确保包含 draft_id |
| 404 错误：草稿不存在 | 草稿ID无效或已过期 | 验证草稿ID，重新创建草稿 |
| 500 错误：遮罩添加失败 | 内部处理异常 | 检查服务器日志，重试操作 |
片段相关问题
| 问题症状 | 可能原因 | 解决方案 |
|---|---|---|
| 404 错误：片段未找到 | 片段ID不存在 | 验证片段ID是否正确 |
| 400 错误：无效的片段类型 | 非视频片段类型 | 确保使用视频片段ID |
| 400 错误：遮罩参数无效 | 参数超出范围 | 检查参数范围（0-100，0-360等） |
性能相关问题
| 问题症状 | 可能原因 | 解决方案 |
|---|---|---|
| 处理缓慢 | 草稿过大或缓存不足 | 优化草稿结构，增加缓存容量 |
| 内存占用过高 | 草稿未及时释放 | 检查缓存清理机制 |
| 并发冲突 | 多个请求同时修改同一草稿 | 使用锁机制或队列处理 |
调试技巧
日志分析
系统提供详细的日志记录，包括：
- 请求处理日志：记录每个 API 请求的详细信息
- 错误日志：记录具体的错误信息和堆栈跟踪
- 性能日志：记录处理时间和资源使用情况
参数验证
在开发阶段，可以使用以下方法验证参数：
python
# 示例：参数验证
def validate_mask_parameters(params):
"""验证遮罩参数的有效性"""
errors = []
# 验证草稿URL
if not params.get('draft_url'):
errors.append('draft_url is required')
# 验证片段ID
if not params.get('segment_ids'):
errors.append('segment_ids is required')
# 验证遮罩参数范围
if params.get('feather', -1) < 0 or params.get('feather', 101) > 100:
errors.append('feather must be between 0 and 100')
return errors更多信息
字段说明、校验规则与示例以 OpenAPI 为准；需要对照源码时请查看 schemas/、service/ 与路由注册处。
文档信息
- 接口文档： docs.jcaigc.cn
- 效果案例： www.jcaigc.cn/workflow
- 开源仓库： capcut-mate