add_masks

POST /add_masks

接口说明

给已有视频片段添加独立蒙版，支持线性、圆形、矩形、爱心、星形等类型，并可设置位置、大小、羽化、旋转和反转。蒙版通过 segment_id 精确定位片段；如果不传片段 ID，草稿必须只有一个视频片段。

给已经存在的视频或图片片段添加蒙版。一个片段只能有一个蒙版；重复调用时返回已有蒙版 ID。

请求参数

参数	类型	必填	默认值	说明
draft_id	string	是	—	草稿 ID
segment_ids	string[]	否	—	要添加蒙版的片段 ID 列表
segment_id	string	否	—	单个片段 ID，和 segment_ids 二选一
name	string	否	线性	蒙版类型，见 GET /get_mask_types
X	number	否	0	蒙版中心相对素材中心的 X 像素，右为正
Y	number	否	0	蒙版中心相对素材中心的 Y 像素，下为正
width	number	否	512	蒙版宽度，单位像素
height	number	否	512	蒙版高度，单位像素
feather	number	否	0	羽化程度，范围 0-100
rotation	number	否	0	顺时针旋转角度
invert	boolean	否	false	是否反转蒙版
roundCorner	number	否	0	矩形蒙版圆角，范围 0-100

如果草稿只有一个视频片段，可以省略 segment_ids 和 segment_id，接口会自动选择它。

请求示例

curl -X POST https://your-domain.example/api/add_masks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VECTCUT_API_KEY" \
  -d '{
    "draft_id": "dfd_cat_demo_001",
    "segment_ids": ["a1b2c3d4e5f6"],
    "name": "圆形",
    "X": 0,
    "Y": 0,
    "width": 720,
    "height": 720,
    "feather": 20,
    "rotation": 0,
    "invert": false
  }'

返回示例

{
  "success": true,
  "output": {
    "draft_id": "dfd_cat_demo_001",
    "draft_url": "https://your-domain.example/api/draft/downloader?draft_id=dfd_cat_demo_001",
    "masks_added": 1,
    "affected_segments": ["a1b2c3d4e5f6"],
    "mask_ids": ["5f4e3d2c1b0a"]
  },
  "error": ""
}