DEV Community

Hommy
Hommy

Posted on

[JCAIGC]Add video special effects

ADD_EFFECTS API Interface Documentation

πŸ“‹ Table of Contents

πŸ”§ Interface Information 

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

Function Description

Add video special effects. This interface is used to add various special effects to CapCut draft, including filters, transitions, animations, beauty effects, and other visual effects. It is suitable for enhancing video visual effects, creating professional video content.

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
effects array βœ… - Special effects material list, supports adding multiple special effects at once

Special Effects Object Structure 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "effects": [
    {
      "effect_type": "filter",
      "effect_name": "Vintage",
      "intensity": 0.8,
      "start_time": 0,
      "duration": 60000000
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Special Effects Parameter Description

Parameter Name Type Required Default Value Description
effect_type string βœ… - Special effect type
effect_name string βœ… - Special effect name
intensity number ❌ 1.0 Special effect intensity, range: 0.0-2.0
start_time number ❌ 0 Start time, unit: microseconds (μs), 1000000μs = 1 second
duration number ❌ auto Duration, unit: microseconds (μs), if not set, apply to the entire video

Special Effect Type Options

Effect Type Description Available Effects
filter Filter effects Vintage, BlackWhite, Warm, Cold, Dreamy, Retro, Cinematic, Portrait
transition Transition effects Fade, SlideLeft, SlideRight, SlideUp, SlideDown, ZoomIn, ZoomOut, Rotate
animation Animation effects Bounce, Shake, Pulse, Flip, Spin, Float, Slide
beauty Beauty effects Smooth, Whiten, SlimFace, BigEyes, RemoveBlemish
stylize Stylization effects Sketch, OilPaint, Watercolor, Emboss, Neon, Glitch
color Color adjustment Brightness, Contrast, Saturation, Hue, Exposure, Shadows, Highlights

Special Effect Intensity Description

Intensity Range Effect Description
0.0 - 0.3 Subtle effect, suitable for fine-tuning
0.3 - 0.7 Moderate effect, suitable for most scenarios
0.7 - 1.0 Strong effect, suitable for prominent special effects
1.0 - 2.0 Very strong effect, suitable for creative expression

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 special effect materials, 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 a vintage filter 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_effects \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "effects": [
      {
        "effect_type": "filter",
        "effect_name": "Vintage",
        "intensity": 0.8,
        "start_time": 0,
        "duration": 60000000
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

2. Add multiple special effects 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_effects \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "effects": [
      {
        "effect_type": "filter",
        "effect_name": "Cinematic",
        "intensity": 0.6,
        "start_time": 0,
        "duration": 30000000
      },
      {
        "effect_type": "transition",
        "effect_name": "Fade",
        "intensity": 1.0,
        "start_time": 25000000,
        "duration": 5000000
      },
      {
        "effect_type": "beauty",
        "effect_name": "Smooth",
        "intensity": 0.5,
        "start_time": 0,
        "duration": 60000000
      },
      {
        "effect_type": "stylize",
        "effect_name": "Glitch",
        "intensity": 0.7,
        "start_time": 40000000,
        "duration": 10000000
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

JavaScript Example 

// Add special effect material function
const addEffects = async (draftUrl, effectList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_effects', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      effects: effectList
    })
  });
  return response.json();
};

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

  const effectList = [
    {
      effect_type: "filter",
      effect_name: "Cinematic",
      intensity: 0.7,
      start_time: 0,
      duration: 60000000
    },
    {
      effect_type: "animation",
      effect_name: "Bounce",
      intensity: 0.8,
      start_time: 20000000,
      duration: 3000000
    },
    {
      effect_type: "color",
      effect_name: "Brightness",
      intensity: 1.2,
      start_time: 0,
      duration: 60000000
    }
  ];

  const result = await addEffects(draftUrl, effectList);
  console.log('Special effects added successfully:', result);
})();
Enter fullscreen mode Exit fullscreen mode

Python Example 

import requests

def add_effects(draft_url, effect_list):
    """Add special effect materials"""
    response = requests.post(
        'https://api.assets.jcaigc.cn/openapi/capcut-mate/v1/add_effects',
        headers={'Content-Type': 'application/json'},
        json={
            "draft_url": draft_url,
            "effects": effect_list
        }
    )
    return response.json()

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

effect_list = [
    {
        "effect_type": "filter",
        "effect_name": "Vintage",
        "intensity": 0.8,
        "start_time": 0,
        "duration": 60000000
    },
    {
        "effect_type": "transition",
        "effect_name": "SlideLeft",
        "intensity": 1.0,
        "start_time": 25000000,
        "duration": 3000000
    },
    {
        "effect_type": "beauty",
        "effect_name": "Smooth",
        "intensity": 0.6,
        "start_time": 0,
        "duration": 60000000
    }
]

result = add_effects(draft_url, effect_list)
print(f"Special effects 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 effects parameter must be an array effects parameter format error Ensure effects is an array type
400 Invalid effect_type Special effect type error Use preset special effect types
400 Invalid effect_name Special effect name error Use preset special effect names
400 Invalid intensity value Intensity value is out of range Intensity should be between 0.0-2.0
400 Invalid time format Time parameter format error Time should be a non-negative number
404 Draft does not exist Specified draft cannot be found Confirm the draft URL is correct and exists
500 Special effect material addition failed Internal service error Contact technical support or try again later
503 Service unavailable System under maintenance Try again later

Notes

  1. Special Effect Combination: Multiple special effects can be combined, but pay attention to the overall visual effect
  2. Intensity Control: Adjust intensity appropriately, too strong special effects may affect video quality
  3. Time Setting: start_time and duration are in microseconds, 1000000 microseconds = 1 second
  4. Special Effect Types: Use preset special effect types and names to ensure compatibility
  5. Performance Considerations: Too many special effects may affect video generation speed
  6. Visual Coordination: Choose appropriate special effects to match the video content and style
  7. Preview Effect: It is recommended to preview the special effect results before generating the final video
  8. Network Stability: Adding special effect materials requires network support, ensure stable network connection

Workflow

  1. Verify draft_url and effects parameters
  2. Validate special effect type and name
  3. Apply intensity and time settings
  4. Generate special effect material objects
  5. Add special effect materials to the special effect track
  6. Update draft configuration file
  7. Return updated draft information

Next Steps

After adding special effect materials, 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
  • 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)