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
}

參數説明

參數名	類型	必填	默認值	説明
draft_url	string	✅	""	目標草稿的完整URL
segment_ids	array	✅	[]	要應用遮罩的片段ID數組
name	string	❌	"線性"	遮罩類型名稱
X	integer	❌		遮罩中心X座標（像素）
Y	integer	❌		遮罩中心Y座標（像素）
width	integer	❌	512	遮罩寬度（像素）
height	integer	❌	512	遮罩高度（像素）
feather	integer	❌		羽化程度（0-100）
rotation	integer	❌		旋轉角度（度）
invert	boolean	❌	false	是否反轉遮罩
roundCorner	integer	❌		圓角半徑（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)

{
  "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_url	string	更新後的草稿URL
masks_added	number	成功添加的遮罩數量
affected_segments	array	受影響的片段ID列表
mask_ids	array	遮罩ID列表

錯誤響應 (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
  }'

錯誤碼説明

錯誤碼	錯誤信息	説明	解決方案
400	draft_url是必填項	缺少草稿URL參數	提供有效的draft_url
400	segment_ids是必填項	缺少片段ID參數	提供有效的segment_ids數組
400	無效的遮罩信息，請檢查遮罩參數是否正確	遮罩參數校驗失敗	檢查遮罩參數是否符合要求
400	羽化程度無效	feather超出範圍	使用0-100範圍內的羽化值
400	旋轉角度無效	rotation超出範圍	使用0-360範圍內的角度值
400	圓角半徑無效	roundCorner超出範圍	使用0-100範圍內的圓角值
404	草稿不存在	指定的草稿URL無效	檢查草稿URL是否正確
404	片段未找到	指定的片段ID不存在	確認片段ID是否正確
400	無效的片段類型	片段類型不支持添加遮罩	確保使用視頻片段ID
404	遮罩類型未找到	指定的遮罩名稱不存在	使用有效的遮罩類型名稱
500	遮罩添加失敗	內部處理錯誤	聯繫技術支持

注意事項

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

相關接口

• 創建草稿
• 添加視頻
• 添加音頻
• 添加圖片
• 保存草稿
• 生成視頻

---

📚 項目資源
GitHub: 搜索capcut-mate即可找到