ADD_MASKS API 接口文档

接口信息

POST /openapi/capcut-mate/v1/add_masks

功能描述

向现有草稿中的指定片段添加遮罩效果。遮罩是视频编辑中的重要功能，通过遮罩可以控制图像的可见区域，创造出各种视觉效果。支持多种遮罩类型（线性、镜面、圆形、矩形、爱心、星形），每种遮罩都可以精确配置位置、大小、羽化、旋转等属性。

更多文档

📖 更多详细文档和教程请访问：https://docs.jcaigc.cn

请求参数

{
   
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "segment_ids": ["d62994b4-25fe-422a-a123-87ef05038558"],
  "name": "圆形",
  "X": 100,
  "Y": 200,
  "width": 300,
  "height": 300,
  "feather": 20,
  "rotation": 0,
  "invert": false,
  "roundCorner": 0
}

参数说明

参数详解

遮罩类型参数

• name: 遮罩类型名称
  • 可选值：线性、镜面、圆形、矩形、爱心、星形
  • 默认值：线性

位置参数

• X: 遮罩中心X坐标（像素）

  • 正值向右移动
  • 负值向左移动
  • 以素材中心为原点

• Y: 遮罩中心Y坐标（像素）

  • 正值向下移动
  • 负值向上移动
  • 以素材中心为原点

尺寸参数

• width: 遮罩宽度（像素）

  • 默认值：512
  • 建议范围：1-2048

• height: 遮罩高度（像素）

  • 默认值：512
  • 建议范围：1-2048

效果参数

• feather: 羽化程度（0-100）

  • 0 = 无羽化（锐利边缘）
  • 100 = 最大羽化（柔和边缘）
  • 默认值：0

• rotation: 旋转角度（度）

  • 0-360度范围
  • 默认值：0

• invert: 是否反转遮罩

  • true = 反转遮罩效果
  • false = 正常遮罩效果
  • 默认值：false

• roundCorner: 圆角半径（0-100）

  • 仅对矩形遮罩有效
  • 0 = 无圆角（直角）
  • 100 = 最大圆角
  • 默认值：0

片段ID参数

• segment_ids: 要应用遮罩的片段ID数组
  • 必须是视频片段ID
  • 支持批量处理多个片段
  • 每个片段只能添加一个遮罩

响应格式

成功响应 (200)

{
   
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "masks_added": 1,
  "affected_segments": ["d62994b4-25fe-422a-a123-87ef05038558"],
  "mask_ids": ["mask_001"]
}

响应字段说明

错误响应 (4xx/5xx)

{
   
  "detail": "错误信息描述"
}

使用示例

cURL 示例

1. 基本遮罩添加

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "segment_ids": ["SEGMENT_ID"],
    "name": "圆形"
  }'

2. 带位置和尺寸的遮罩

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "segment_ids": ["SEGMENT_ID"],
    "name": "矩形",
    "X": 100,
    "Y": 50,
    "width": 400,
    "height": 300
  }'

3. 带效果参数的遮罩

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "segment_ids": ["SEGMENT_ID"],
    "name": "线性",
    "feather": 30,
    "rotation": 45,
    "invert": true
  }'

4. 矩形遮罩带圆角

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "segment_ids": ["SEGMENT_ID"],
    "name": "矩形",
    "roundCorner": 50
  }'

错误码说明

注意事项

1. 片段要求: 只有视频片段（VideoSegment）支持添加遮罩
2. 遮罩限制: 每个片段只能添加一个遮罩，重复添加不会报错，会返回现有遮罩信息
3. 坐标系统: X、Y坐标以像素为单位，原点位于素材中心
4. 参数范围:
   • feather: 0-100，羽化程度
   • rotation: 0-360度，旋转角度
   • roundCorner: 0-100，圆角半径（仅矩形遮罩有效）
5. 批量处理: 支持同时为多个片段添加相同配置的遮罩
6. 遮罩类型: 支持线性、镜面、圆形、矩形、爱心、星形六种遮罩类型
7. 性能考虑: 避免同时添加大量遮罩

工作流程

1. 验证必填参数（draft_url, segment_ids）
2. 检查片段ID的有效性
3. 从缓存中获取草稿
4. 查找并验证遮罩类型
5. 为每个片段添加遮罩
6. 保存草稿
7. 返回遮罩信息

相关接口

• 创建草稿
• 添加视频
• 添加音频
• 添加图片
• 保存草稿
• 生成视频