添加遮罩接口文档 #

接口概述 #

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

更多文档 #

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

接口信息 #

• 请求方式: POST
• 接口路径: /openapi/capcut-mate/v1/add_masks
• Content-Type: application/json

请求参数 #

请求体 (Body) #

支持的遮罩类型 #

遮罩配置详解 #

• 位置控制: X、Y参数控制遮罩在画面中的位置
• 尺寸控制: width、height控制遮罩的大小
• 羽化效果: feather参数控制边缘的柔化程度，值越大边缘越柔和
• 旋转变换: rotation参数控制遮罩的旋转角度
• 反转效果: invert参数可以反转遮罩的显示/隐藏区域
• 圆角处理: roundCorner参数为矩形遮罩添加圆角效果

请求示例 #

curl -X POST "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_masks" \
-H "Content-Type: application/json" \
-d '{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "segment_ids": ["d62994b4-25fe-422a-a123-87ef05038558", "e73995c5-36ef-533b-b234-98fg16149669"],
  "name": "圆形",
  "X": 100,
  "Y": 200,
  "width": 300,
  "height": 300,
  "feather": 20,
  "rotation": 0,
  "invert": false,
  "roundCorner": 0
}'

响应格式 #

成功响应 #

{
  "code": 0,
  "message": "Success",
  "data": {
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "masks_added": 2,
    "affected_segments": ["d62994b4-25fe-422a-a123-87ef05038558", "e73995c5-36ef-533b-b234-98fg16149669"],
    "mask_ids": ["mask_001", "mask_002"]
  }
}

响应字段说明:

• draft_url: 草稿URL
• masks_added: 成功添加的遮罩数量
• affected_segments: 受影响的片段ID列表
• mask_ids: 遮罩ID列表

错误响应 #

{
  "code": 2023,
  "message": "无效的遮罩信息，请检查遮罩参数是否正确"
}

错误码说明 #

使用说明 #

1. 片段要求: 只有视频片段（VideoSegment）支持添加遮罩
2. 遮罩限制: 每个片段只能添加一个遮罩，重复添加会失败
3. 坐标系统: X、Y坐标以像素为单位，原点位于素材中心
4. 参数范围:
   • feather: 0-100，羽化程度
   • rotation: 0-360度，旋转角度
   • roundCorner: 0-100，圆角半径（仅矩形遮罩有效）
5. 批量处理: 支持同时为多个片段添加相同配置的遮罩

应用场景 #

创意视觉效果 #

• 聚光灯效果: 使用圆形遮罩突出画面重点
• 窗口效果: 使用矩形遮罩创建窗口视觉
• 浪漫场景: 使用爱心遮罩营造浪漫氛围
• 装饰效果: 使用星形遮罩增加装饰元素

画面过渡 #

• 渐变显示: 使用线性遮罩实现渐进显示效果
• 对称效果: 使用镜面遮罩创建对称视觉
• 柔和边缘: 通过羽化参数实现柔和的边缘过渡

内容遮挡 #

• 隐私保护: 遮挡敏感信息区域
• 焦点引导: 突出重要内容，弱化无关区域
• 艺术创作: 创造独特的视觉艺术效果

注意事项 #

• 遮罩效果只对视频片段有效，不支持音频、文本或贴纸片段
• 添加遮罩后会影响片段的视觉呈现，请确保遮罩配置符合预期
• 遮罩参数的单位和坐标系以素材自身为基准
• 建议在添加遮罩前预览效果，确保达到预期的视觉效果
• 遮罩的渲染性能可能影响导出速度，请根据需要合理使用

相关接口 #

• 创建草稿 - 创建新的剪映草稿
• 添加视频 - 向草稿添加视频内容
• 添加特效 - 向草稿添加视频特效
• 保存草稿 - 保存草稿更改