简创AIGC官方文档

主题切换

ADD_MASKS API 接口文档 ​

🌐 语言切换 ​

中文版 | English

接口信息 ​

POST /openapi/capcut-mate/v1/add_masks

功能描述 ​

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

请求参数 ​

json
{
  "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
}

参数说明 ​

参数名类型必填默认值说明
draft_urlstring✅""目标草稿的完整URL
segment_idsarray✅[]要应用遮罩的片段ID数组
namestring❌"线性"遮罩类型名称
Xinteger❌0遮罩中心X坐标（像素）
Yinteger❌0遮罩中心Y坐标（像素）
widthinteger❌512遮罩宽度（像素）
heightinteger❌512遮罩高度（像素）
featherinteger❌0羽化程度（0-100）
rotationinteger❌0旋转角度（度）
invertboolean❌false是否反转遮罩
roundCornerinteger❌0圆角半径（0-100）

参数详解 ​

遮罩类型参数 ​

  • 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) ​

json
{
  "code": 0,
  "message": "success",
  "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"]
}

响应字段说明 ​

字段名类型说明
draft_urlstring更新后的草稿URL
masks_addednumber成功添加的遮罩数量
affected_segmentsarray受影响的片段ID列表
mask_idsarray遮罩ID列表

错误响应 ​

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

使用示例 ​

cURL 示例 ​

1. 基本遮罩添加 ​

bash
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. 带位置和尺寸的遮罩 ​

bash
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. 带效果参数的遮罩 ​

bash
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. 矩形遮罩带圆角 ​

bash
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
  }'

错误码说明 ​

错误码错误信息说明解决方案
1001参数校验失败请求体未通过参数校验（如 X、width 传了小数）检查参数类型与必填项
2001无效的草稿URLdraft_url 缺失、格式错误或草稿不在缓存中使用 create_draft 返回的 draft_url
2015片段未找到指定的片段ID不存在确认片段ID是否正确
2016无效的片段类型片段类型不支持添加遮罩确保使用视频片段ID
2023无效的遮罩信息segment_ids 为空至少提供一个片段ID
2024遮罩添加失败写入草稿过程中出错检查草稿状态后重试
2025遮罩类型未找到指定的遮罩名称不存在使用 线性 / 镜面 / 圆形 / 矩形 / 爱心 / 星形
2042草稿锁获取超时同一草稿并发操作稍后重试

注意事项 ​

  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. 返回遮罩信息

相关接口 ​

版权所有 © 2025 简创AIGC