遮罩效果接口

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考量
8. 故障排查指南
9. 结论
10. 附录

简介

本文档是遮罩效果接口的详细 API 文档，涵盖遮罩的创建与应用流程，包括遮罩形状定义、几何参数配置、羽化与反相效果；解释遮罩坐标系统、尺寸调整、旋转角度与圆角处理；说明遮罩的实时预览、多遮罩叠加与遮罩与视频内容的合成规则；并提供最佳实践、性能建议、常见问题与调试方法。

项目结构

该功能围绕"请求模型 → 路由 → 服务 → 底层视频片段与遮罩元数据"展开，形成清晰的分层结构：

• 请求模型层：定义请求与响应的数据结构
• 路由层：暴露 HTTP 接口，转发请求至服务层
• 服务层：执行业务逻辑，校验参数、定位片段、调用底层添加遮罩
• 底层实现层：视频片段类负责遮罩对象的构造与导出

核心组件

• 接口路径：POST /openapi/capcut-mate/v1/add_masks
• 功能：向指定草稿中的视频片段添加遮罩效果，支持多种遮罩类型与参数配置
• 请求体字段：草稿 URL、片段 ID 数组、遮罩类型名称、中心坐标、宽高、羽化、旋转、反相、圆角
• 响应体字段：更新后的草稿 URL、添加成功的遮罩数量、受影响片段 ID 列表、遮罩 ID 列表

架构总览

遮罩接口的调用链路：

详细组件分析

接口定义与参数说明

• 接口路径：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 描述遮罩的资源与默认参数

视频片段与遮罩对象

• 视频片段 VideoSegment 提供添加遮罩的方法 add_mask(…)
• 遮罩对象 Mask 表示具体的遮罩实例，包含中心坐标、宽高、旋转、反相、羽化、圆角等参数，并导出为 JSON
• add_mask(…) 会根据遮罩类型与参数计算内部尺寸与比例，必要时对非矩形遮罩限制圆角与矩形宽度参数

服务层业务流程

• 参数校验：草稿 URL 有效性、片段 ID 数组非空
• 类型解析：根据 name 查找遮罩类型
• 片段遍历：逐个定位片段，校验类型为视频片段，且每个片段仅允许一个遮罩
• 尺寸换算：以素材宽高为基准，将 height 转换为 size（占素材高的比例），width 在矩形遮罩时转换为 rect_width
• 添加遮罩：调用 VideoSegment.add_mask(…)，按类型区分是否允许圆角与矩形宽度
• 结果返回：保存草稿并返回结果

路由与请求/响应模型

• 路由：/v1/add_masks，POST，接收 AddMasksRequest，返回 AddMasksResponse
• 请求模型：定义字段与默认值
• 响应模型：定义返回字段

遮罩参数对比分析

基于代码实现的分析：

坐标系统说明

• 像素坐标系统：X、Y 使用像素坐标，原点位于素材中心
• 尺寸参数：width、height 使用像素值；内部会根据素材宽高转换为相对比例与矩形宽度
• 参数范围：所有数值参数都使用整数形式，范围在合理区间内

功能特性

• 遮罩类型：支持线性、镜面、圆形、矩形、爱心、星形六种类型
• 参数配置：支持羽化、旋转、反相、圆角等效果参数
• 尺寸换算：自动处理像素到比例的转换，确保遮罩正确显示

依赖关系分析

• 路由依赖服务层
• 服务层依赖视频片段与遮罩元数据
• 遮罩类型依赖遮罩元数据
• 请求/响应模型独立于实现，便于接口文档化与契约约束

性能考量

• 批量处理：支持一次为多个片段添加遮罩，但应避免同时对大量片段并发添加，以免增加草稿保存压力
• 参数范围：合理设置羽化、旋转、圆角等参数，避免极端值导致渲染开销增大
• 片段限制：每个片段仅允许一个遮罩，重复添加会复用现有遮罩，减少重复创建成本
• 草稿保存：每次添加完成后进行保存，建议在批量操作后统一触发保存，降低频繁 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 范围内调整

批量处理建议

• 支持同时为多个片段添加相同配置的遮罩
• 避免同时添加大量遮罩，建议分批处理
• 合理设置参数范围，避免极端值影响性能

附录

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