# 遮罩效果接口

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

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

## 项目结构
该功能围绕"请求模型 → 路由 → 服务 → 底层视频片段与遮罩元数据"展开，形成清晰的分层结构：
- 请求模型层：定义请求与响应的数据结构
- 路由层：暴露 HTTP 接口，转发请求至服务层
- 服务层：执行业务逻辑，校验参数、定位片段、调用底层添加遮罩
- 底层实现层：视频片段类负责遮罩对象的构造与导出

```mermaid
graph TB
subgraph "接口层"
R["路由 /v1/add_masks"]
end
subgraph "服务层"
S["服务 add_masks(...)"]
end
subgraph "模型层"
M1["请求模型 AddMasksRequest"]
M2["响应模型 AddMasksResponse"]
end
subgraph "实现层"
V["视频片段 VideoSegment.add_mask(...)"]
T["遮罩类型 MaskType"]
E["遮罩元数据 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 列表


## 架构总览
遮罩接口的调用链路：

```mermaid
sequenceDiagram
participant C as "客户端"
participant RT as "路由 /v1/add_masks"
participant SV as "服务 add_masks(...)"
participant SC as "脚本文件 ScriptFile"
participant VS as "视频片段 VideoSegment"
participant MS as "遮罩对象 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 描述遮罩的资源与默认参数

```mermaid
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(...) 会根据遮罩类型与参数计算内部尺寸与比例，必要时对非矩形遮罩限制圆角与矩形宽度参数

```mermaid
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(...)，按类型区分是否允许圆角与矩形宽度
- 结果返回：保存草稿并返回结果

```mermaid
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 使用像素值；内部会根据素材宽高转换为相对比例与矩形宽度
- **参数范围**：所有数值参数都使用整数形式，范围在合理区间内

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


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

```mermaid
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 范围内调整

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

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

【开源剪映小助手】遮罩效果接口

前端

音视频

开发工具

遮罩效果API文档详解：提供6种遮罩类型（线性/圆形/矩形等），支持坐标定位、尺寸调整、羽化、旋转、反相等参数配置。接口采用分层架构，包含请求模型、路由、服务层和底层实现，支持批量操作与参数校验。提供故障排查指南与性能优化建议，帮助开发者快速实现视频遮罩特效。

数据结构

路由

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【开源剪映小助手】遮罩效果接口-腾讯云开发者社区-腾讯云

【开源剪映小助手】遮罩效果接口

【开源剪映小助手】遮罩效果接口

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐