遮罩效果接口
目录
简介
本文档是遮罩效果接口的详细 API 文档，涵盖遮罩的创建与应用流程，包括遮罩形状定义、几何参数配置、羽化与反相效果；解释遮罩坐标系统、尺寸调整、旋转角度与圆角处理；说明遮罩的实时预览、多遮罩叠加与遮罩与视频内容的合成规则；并提供最佳实践、性能建议、常见问题与调试方法。
项目结构
该功能围绕"请求模型 → 路由 → 服务 → 底层视频片段与遮罩元数据"展开，形成清晰的分层结构：
- 请求模型层：定义请求与响应的数据结构
- 路由层：暴露 HTTP 接口，转发请求至服务层
- 服务层：执行业务逻辑，校验参数、定位片段、调用底层添加遮罩
- 底层实现层：视频片段类负责遮罩对象的构造与导出
graph TB
subgraph "接口层"
R["路由<br/>/v1/add_masks"]
end
subgraph "服务层"
S["服务<br/>add_masks(...)"]
end
subgraph "模型层"
M1["请求模型<br/>AddMasksRequest"]
M2["响应模型<br/>AddMasksResponse"]
end
subgraph "实现层"
V["视频片段<br/>VideoSegment.add_mask(...)"]
T["遮罩类型<br/>MaskType"]
E["遮罩元数据<br/>MaskMeta"]
end
R --> S
S --> V
S --> T
T --> E
M1 --> R
R --> M2
核心组件
- 接口路径：POST /openapi/capcut-mate/v1/add_masks
- 功能：向指定草稿中的视频片段添加遮罩效果，支持多种遮罩类型与参数配置
- 请求体字段：草稿 URL、片段 ID 数组、遮罩类型名称、中心坐标、宽高、羽化、旋转、反相、圆角
- 响应体字段：更新后的草稿 URL、添加成功的遮罩数量、受影响片段 ID 列表、遮罩 ID 列表
架构总览
遮罩接口的调用链路：
sequenceDiagram
participant C as "客户端"
participant RT as "路由<br/>/v1/add_masks"
participant SV as "服务<br/>add_masks(...)"
participant SC as "脚本文件<br/>ScriptFile"
participant VS as "视频片段<br/>VideoSegment"
participant MS as "遮罩对象<br/>Mask"
C->>RT : POST /openapi/capcut-mate/v1/add_masks
RT->>SV : 校验并转发参数
SV->>SC : 从缓存获取草稿
SV->>SV : 查找遮罩类型
SV->>VS : 遍历片段ID并添加遮罩
VS->>MS : 构造遮罩对象并绑定到片段
SV->>SC : 保存草稿
SV-->>RT : 返回结果
RT-->>C : 响应
详细组件分析
接口定义与参数说明
- 接口路径：POST /openapi/capcut-mate/v1/add_masks
请求体字段
- draft_url：草稿 URL（必填）
- segment_ids：片段 ID 数组（必填）
- name：遮罩类型名称（可选，默认"线性"）
- X、Y：遮罩中心坐标（像素，以素材中心为原点）
- width、height：遮罩宽高（像素）
- feather：羽化程度（0-100）
- rotation：旋转角度（度，0-360）
- invert：是否反转遮罩（布尔）
- roundCorner：圆角半径（0-100，仅矩形遮罩有效）
响应体字段
- draft_url：更新后的草稿 URL
- masks_added：成功添加的遮罩数量
- affected_segments：受影响的片段 ID 列表
- mask_ids：遮罩 ID 列表
遮罩类型与元数据
- 支持的遮罩类型：线性、镜面、圆形、矩形、爱心、星形
- 遮罩类型通过枚举 MaskType 定义，包含资源类型、资源 ID、效果 ID、MD5 与默认宽高比
- 遮罩元数据 MaskMeta 描述遮罩的资源与默认参数
classDiagram
class EffectEnum {
+from_name(name)
}
class MaskMeta {
+string name
+string resource_type
+string resource_id
+string effect_id
+string md5
+float default_aspect_ratio
}
class MaskType {
+线性
+镜面
+圆形
+矩形
+爱心
+星形
}
EffectEnum <|-- MaskType
MaskType --> MaskMeta : "包含"
视频片段与遮罩对象
- 视频片段 VideoSegment 提供添加遮罩的方法 add_mask(...)
- 遮罩对象 Mask 表示具体的遮罩实例，包含中心坐标、宽高、旋转、反相、羽化、圆角等参数，并导出为 JSON
- add_mask(...) 会根据遮罩类型与参数计算内部尺寸与比例，必要时对非矩形遮罩限制圆角与矩形宽度参数
classDiagram
class VideoSegment {
+add_mask(mask_type, center_x, center_y, size, rotation, feather, invert, rect_width, round_corner)
+mask : Mask
+material_size : (w,h)
}
class Mask {
+global_id : string
+center_x : float
+center_y : float
+width : float
+height : float
+aspect_ratio : float
+rotation : float
+invert : bool
+feather : float
+round_corner : float
+export_json() dict
}
VideoSegment --> Mask : "创建并持有"
服务层业务流程
- 参数校验：草稿 URL 有效性、片段 ID 数组非空
- 类型解析：根据 name 查找遮罩类型
- 片段遍历：逐个定位片段，校验类型为视频片段，且每个片段仅允许一个遮罩
- 尺寸换算：以素材宽高为基准，将 height 转换为 size（占素材高的比例），width 在矩形遮罩时转换为 rect_width
- 添加遮罩：调用 VideoSegment.add_mask(...)，按类型区分是否允许圆角与矩形宽度
- 结果返回：保存草稿并返回结果
flowchart TD
Start(["开始"]) --> CheckDraft["校验草稿URL与缓存"]
CheckDraft --> DraftOK{"有效?"}
DraftOK -- 否 --> ErrDraft["抛出草稿无效错误"]
DraftOK -- 是 --> ParseType["解析遮罩类型"]
ParseType --> TypeOK{"类型存在?"}
TypeOK -- 否 --> ErrType["抛出遮罩类型错误"]
TypeOK -- 是 --> LoopSeg["遍历片段ID"]
LoopSeg --> FindSeg["定位片段"]
FindSeg --> IsVideo{"是否视频片段?"}
IsVideo -- 否 --> ErrSeg["抛出片段类型错误"]
IsVideo -- 是 --> HasMask{"片段已有遮罩?"}
HasMask -- 是 --> ReturnOld["返回现有遮罩ID"]
HasMask -- 否 --> CalcSize["计算size与rect_width"]
CalcSize --> AddMask["调用add_mask(...)"]
AddMask --> Save["保存草稿"]
Save --> Done(["结束"])
ErrDraft --> Done
ErrType --> Done
ErrSeg --> Done
ReturnOld --> Done
路由与请求/响应模型
- 路由：/v1/add_masks，POST，接收 AddMasksRequest，返回 AddMasksResponse
- 请求模型：定义字段与默认值
- 响应模型：定义返回字段
遮罩参数对比分析
基于代码实现的分析：
坐标系统说明
- 像素坐标系统：X、Y 使用像素坐标，原点位于素材中心
- 尺寸参数：width、height 使用像素值；内部会根据素材宽高转换为相对比例与矩形宽度
- 参数范围：所有数值参数都使用整数形式，范围在合理区间内
功能特性
- 遮罩类型：支持线性、镜面、圆形、矩形、爱心、星形六种类型
- 参数配置：支持羽化、旋转、反相、圆角等效果参数
- 尺寸换算：自动处理像素到比例的转换，确保遮罩正确显示
依赖关系分析
- 路由依赖服务层
- 服务层依赖视频片段与遮罩元数据
- 遮罩类型依赖遮罩元数据
- 请求/响应模型独立于实现，便于接口文档化与契约约束
graph LR
R["路由"] --> S["服务"]
S --> V["视频片段"]
S --> T["遮罩类型"]
T --> E["遮罩元数据"]
M1["请求模型"] --> R
R --> M2["响应模型"]
性能考量
- 批量处理：支持一次为多个片段添加遮罩，但应避免同时对大量片段并发添加，以免增加草稿保存压力
- 参数范围：合理设置羽化、旋转、圆角等参数，避免极端值导致渲染开销增大
- 片段限制：每个片段仅允许一个遮罩，重复添加会复用现有遮罩，减少重复创建成本
- 草稿保存：每次添加完成后进行保存，建议在批量操作后统一触发保存，降低频繁 IO
故障排查指南
常见错误与解决
- 草稿 URL 无效或不在缓存中：检查 draft_url 的 draft_id 是否正确
- 片段 ID 为空或不存在：确认 segment_ids 非空且存在于草稿中
- 片段类型不支持：确保片段为视频片段（VideoSegment）
- 遮罩类型不存在：确认 name 属于支持的类型之一
- 遮罩添加失败：检查参数合法性与片段状态
参数范围校验
- 羽化：0-100
- 旋转：0-360
- 圆角：0-100（仅矩形遮罩有效）
- 日志与追踪
- 服务层记录关键步骤与错误信息，便于定位问题
- 响应包含受影响片段与遮罩 ID，可用于后续验证
结论
遮罩效果接口提供了完整的遮罩创建与应用能力，覆盖多种遮罩类型与丰富的几何/效果参数。通过清晰的分层设计与严格的参数校验，能够在保证易用性的同时满足复杂场景需求。
附录
遮罩参数与坐标系统说明
- 坐标系统：X、Y 以像素为单位，原点位于素材中心
- 尺寸参数：width、height 以像素为单位；内部会根据素材宽高转换为相对比例与矩形宽度
- 羽化：0 表示锐利边缘，100 表示最大柔和边缘
- 旋转：0-360 度
- 圆角：0-100，仅矩形遮罩有效
- 反相：true 时反转遮罩效果
多遮罩叠加与合成规则
- 每个视频片段仅允许一个遮罩；重复添加将返回现有遮罩 ID
- 遮罩与视频内容的合成由底层实现决定，接口层不改变合成规则
实时预览与效果验证
- 实时预览：建议在调用接口后立即保存草稿并生成视频进行验证
- 效果验证：通过响应中的 affected_segments 与 mask_ids 核对遮罩是否正确应用
- 调试方法：开启服务端日志，观察关键步骤与错误信息；逐步缩小参数范围定位问题
高级遮罩操作最佳实践
遮罩类型选择
- 线性遮罩：适合简单的渐变效果
- 镜面遮罩：创造对称反射效果
- 圆形遮罩：突出圆形区域
- 矩形遮罩：最灵活，支持圆角和尺寸调整
- 爱心遮罩：特殊形状效果
- 星形遮罩：装饰性效果
参数配置策略
- 位置调整：使用 X、Y 参数精确定位遮罩中心
- 尺寸优化：根据素材分辨率调整 width、height
- 羽化设置：0-100 范围内根据视觉效果调整
- 旋转应用：0-360 度范围内实现任意角度旋转
- 圆角控制：仅对矩形遮罩有效，0-100 范围内调整
批量处理建议
- 支持同时为多个片段添加相同配置的遮罩
- 避免同时添加大量遮罩，建议分批处理
- 合理设置参数范围，避免极端值影响性能
