add_mask_keyframes

POST /add_mask_keyframes

接口说明

给已有蒙版添加位置、大小、羽化或旋转关键帧，形成蒙版动画。批量传入时每一项都要有 segment_id 和秒单位的 offset；兼容的 offset_us 仅用于旧调用迁移，不推荐新接口使用。

给已经添加蒙版的视频或图片片段添加蒙版关键帧。调用前先使用 add_masks 添加蒙版。

时间单位

本服务统一使用秒：

offset：相对片段起点的秒数
time：offset 的别名，单位也是秒
offset_us：只在需要兼容微秒输入时使用

请求参数

参数	类型	必填	说明
`draft_id`	string	是	草稿 ID
`keyframes`	object[]	是	关键帧列表
`keyframes[].segment_id`	string	是	目标片段 ID
`keyframes[].offset`	number	是	相对片段起点的秒数
`keyframes[].X`	number	否	蒙版中心 X 像素
`keyframes[].Y`	number	否	蒙版中心 Y 像素
`keyframes[].width`	number	否	蒙版宽度像素
`keyframes[].height`	number	否	蒙版高度像素
`keyframes[].feather`	number	否	羽化程度 `0-100`
`keyframes[].rotation`	number	否	旋转角度

每条关键帧至少要提供 X、Y、width、height、feather、rotation 中的一个。

请求示例

bash

curl -X POST https://your-domain.example/api/add_mask_keyframes \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VECTCUT_API_KEY" \
  -d '{
    "draft_id": "dfd_cat_demo_001",
    "keyframes": [
      {
        "segment_id": "a1b2c3d4e5f6",
        "offset": 0,
        "X": -120,
        "Y": 0,
        "width": 500,
        "height": 500
      },
      {
        "segment_id": "a1b2c3d4e5f6",
        "offset": 2.5,
        "X": 120,
        "Y": 40,
        "width": 820,
        "height": 820,
        "rotation": 45
      }
    ]
  }'

返回示例

json

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

keyframes_added 按属性计数：X、Y、width、height、feather、rotation 各算一条。

add_mask_keyframes ​

接口说明 ​

时间单位 ​

请求参数 ​