ADD_MASKS API Documentation #

🌐 Language Switch #

中文版 | English

Interface Information #

POST /openapi/capcut-mate/v1/add_masks

Function Description #

Add mask effects to existing drafts. This interface is used to add various shape masks to control visible areas of the screen in Jianying drafts. Masks can be used to create interesting visual effects and focus attention on specific areas.

More Documentation #

📖 For more detailed documentation and tutorials, please visit: https://docs.jcaigc.cn

Request Parameters #

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "segment_ids": ["segment1-uuid", "segment2-uuid"],
  "name": "Circle Mask",
  "X": 0.5,
  "Y": 0.5,
  "width": 0.3,
  "height": 0.3,
  "feather": 0.1,
  "rotation": 0,
  "invert": false,
  "roundCorner": 0.2
}

Parameter Description #

Response Format #

Success Response (200) #

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "masks_added": 2,
  "affected_segments": ["segment1-uuid", "segment2-uuid"],
  "mask_ids": ["mask1-uuid", "mask2-uuid"]
}

Response Field Description #

Error Response (4xx/5xx) #

{
  "detail": "Error message description"
}

Usage Examples #

cURL Examples #

1. Basic Circle Mask #

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": ["segment1-uuid"],
    "name": "Circle Mask",
    "X": 0.5,
    "Y": 0.5,
    "width": 0.4,
    "height": 0.4
  }'

2. Rectangle Mask with Effects #

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": ["segment1-uuid", "segment2-uuid"],
    "name": "Rectangle Mask",
    "X": 0.3,
    "Y": 0.4,
    "width": 0.5,
    "height": 0.3,
    "feather": 0.1,
    "roundCorner": 0.1
  }'

3. Inverted Mask #

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": ["segment1-uuid"],
    "name": "Heart Mask",
    "X": 0.5,
    "Y": 0.5,
    "width": 0.3,
    "height": 0.3,
    "invert": true
  }'

Error Code Description #

Notes #

1. Coordinate System: Position values use normalized coordinates (0.0-1.0)
2. Size Values: Width and height are relative to screen size
3. Mask Types: Support various mask shapes (circle, rectangle, heart, etc.)
4. Feather Effect: Softens mask edges for natural transitions
5. Rotation: Rotation angle in degrees
6. Invert: When true, shows area outside the mask

Workflow #

1. Validate required parameters
2. Check segment existence
3. Create mask with specified parameters
4. Apply mask to segments
5. Save and encrypt draft
6. Return processing result

Related Interfaces #

• Create Draft
• Add Videos
• Add Images
• Save Draft