DEV Community

Hommy
Hommy

Posted on

[JCAIGC]Add mask effects

ADD_MASKS API Interface Documentation

📋 Table of Contents

🔧 Interface Information 

POST /openapi/capcut-mate/v1/add_masks
Enter fullscreen mode Exit fullscreen mode

Function Description

Add mask effects. This interface is used to add various mask effects to elements in CapCut draft, including circular masks, rectangular masks, star masks, heart-shaped masks, and other shape masks. It is suitable for creating picture-in-picture effects, highlighting key content, protecting privacy, and other scenarios.

More Documentation

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

Request Parameters

Request Body (application/json)

Parameter Name Type Required Default Value Description
draft_url string ✅ - Target draft URL, format: https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=xxx
masks array ✅ - Mask effect list, supports adding multiple mask effects at once

Mask Object Structure 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "masks": [
    {
      "element_id": "video_001",
      "mask_type": "circle",
      "position": "center",
      "size": 0.5,
      "feather": 0.2,
      "invert": false
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Mask Parameter Description

Parameter Name Type Required Default Value Description
element_id string ✅ - Element ID, used to identify the target element
mask_type string ✅ - Mask shape type
position string ❌ "center" Mask position
size number ❌ 1.0 Mask size, range: 0.1-2.0
feather number ❌ 0.0 Mask feathering degree, range: 0.0-1.0
invert boolean ❌ false Whether to invert the mask

Mask Type Options

Mask Type Description Application Scenario
circle Circular mask Portrait highlighting, circular picture-in-picture
rectangle Rectangular mask Regular picture-in-picture, cropping
star Star mask Creative transitions, special effects
heart Heart-shaped mask Romantic themes, emotional expression
triangle Triangular mask Geometric effects, creative layouts
ellipse Elliptical mask Portrait beautification, soft transitions

Position Options

Position Value Description Coordinate Position
top_left Top left corner (0%, 0%)
top_center Top center (50%, 0%)
top_right Top right corner (100%, 0%)
center_left Center left (0%, 50%)
center Absolute center (50%, 50%)
center_right Center right (100%, 50%)
bottom_left Bottom left corner (0%, 100%)
bottom_center Bottom center (50%, 100%)
bottom_right Bottom right corner (100%, 100%)

Custom Position

In addition to using preset positions, you can also use custom coordinates:

{
  "position": {
    "x": 100,
    "y": 200,
    "unit": "px"
  }
}
Enter fullscreen mode Exit fullscreen mode

Feather Parameter Description

Feather Value Effect Description
0.0 No feathering, edges are sharp
0.1 - 0.3 Slight feathering, soft edges
0.3 - 0.6 Moderate feathering, obvious softening
0.6 - 1.0 Strong feathering, very soft edges

Size Parameter Description

Size Range Effect Description
0.1 - 0.3 Very small mask, suitable for highlighting details
0.3 - 0.6 Small mask, suitable for partial display
0.6 - 1.0 Medium mask, suitable for regular picture-in-picture
1.0 - 1.5 Large mask, suitable for full-screen effects
1.5 - 2.0 Extra large mask, suitable for special creative effects

Response Format

Success Response (200) 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "tip_url": "https://help.assets.jcaigc.cn/draft-usage"
}
Enter fullscreen mode Exit fullscreen mode

Response Field Description

Field Name Type Description
draft_url string Draft URL after adding mask effects, same as the request URL
tip_url string Draft usage help document URL

Error Response (4xx/5xx) 

{
  "detail": "Error message description"
}
Enter fullscreen mode Exit fullscreen mode

Usage Examples

cURL Example

1. Add circular mask 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "masks": [
      {
        "element_id": "video_001",
        "mask_type": "circle",
        "position": "center",
        "size": 0.6,
        "feather": 0.2,
        "invert": false
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

2. Add multiple mask effects 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_masks \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "masks": [
      {
        "element_id": "image_001",
        "mask_type": "star",
        "position": "top_left",
        "size": 0.4,
        "feather": 0.3,
        "invert": false
      },
      {
        "element_id": "video_002",
        "mask_type": "heart",
        "position": "bottom_right",
        "size": 0.5,
        "feather": 0.1,
        "invert": true
      },
      {
        "element_id": "image_002",
        "mask_type": "triangle",
        "position": "center",
        "size": 0.8,
        "feather": 0.4,
        "invert": false
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

JavaScript Example 

// Add mask effect function
const addMasks = async (draftUrl, maskList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_masks', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      masks: maskList
    })
  });
  return response.json();
};

// Usage example
(async () => {
  const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";

  const maskList = [
    {
      element_id: "video_001",
      mask_type: "circle",
      position: "center",
      size: 0.6,
      feather: 0.2,
      invert: false
    },
    {
      element_id: "image_001",
      mask_type: "star",
      position: "top_left",
      size: 0.4,
      feather: 0.3,
      invert: false
    }
  ];

  const result = await addMasks(draftUrl, maskList);
  console.log('Masks added successfully:', result);
})();
Enter fullscreen mode Exit fullscreen mode

Python Example 

import requests

def add_masks(draft_url, mask_list):
    """Add mask effects"""
    response = requests.post(
        'https://api.assets.jcaigc.cn/openapi/capcut-mate/v1/add_masks',
        headers={'Content-Type': 'application/json'},
        json={
            "draft_url": draft_url,
            "masks": mask_list
        }
    )
    return response.json()

# Usage example
draft_url = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"

mask_list = [
    {
        "element_id": "video_001",
        "mask_type": "circle",
        "position": "center",
        "size": 0.6,
        "feather": 0.2,
        "invert": false
    },
    {
        "element_id": "image_001",
        "mask_type": "heart",
        "position": "bottom_right",
        "size": 0.5,
        "feather": 0.1,
        "invert": true
    }
]

result = add_masks(draft_url, mask_list)
print(f"Masks added successfully: {result['draft_url']}")
Enter fullscreen mode Exit fullscreen mode

Error Code Description

Error Code Error Message Description Solution
400 draft_url is required Missing draft URL parameter Provide a valid draft_url
400 masks parameter must be an array masks parameter format error Ensure masks is an array type
400 element_id cannot be empty Element ID cannot be empty Provide a valid element_id
400 Invalid mask_type Mask type error Use preset mask types
400 Invalid size value Size value is out of range Size should be between 0.1-2.0
400 Invalid feather value Feather value is out of range Feather should be between 0.0-1.0
404 Draft does not exist Specified draft cannot be found Confirm the draft URL is correct and exists
500 Mask effect addition failed Internal service error Contact technical support or try again later
503 Service unavailable System under maintenance Try again later

Notes

  1. Element ID: Make sure the element_id exists and is unique, used to identify the target element
  2. Mask Type: Use preset mask types to ensure compatibility
  3. Size Control: Adjust the mask size appropriately to achieve the best visual effect
  4. Feathering: Appropriate feathering can make mask edges softer and more natural
  5. Position Layout: Choose appropriate positions to achieve the desired visual effect
  6. Invert Function: The invert parameter can create negative effects, suitable for special creative needs
  7. Multiple Masks: Multiple mask effects can be applied to the same element
  8. Network Stability: Adding mask effects requires network support, ensure stable network connection

Workflow

  1. Verify draft_url and masks parameters
  2. Validate element_id and mask types
  3. Apply position, size, feathering, and invert settings
  4. Generate mask effect objects
  5. Apply mask effects to the corresponding elements
  6. Update draft configuration file
  7. Return updated draft information

Next Steps

After adding mask effects, you can continue to use the following interfaces to improve the video:

  • add_videos: Add video materials
  • add_images: Add image materials
  • add_audios: Add audio materials
  • add_captions: Add subtitles
  • add_effects: Add special effects
  • save_draft: Save draft
  • gen_video: Export video

Related Interfaces

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

Top comments (0)