DEV Community

Hommy
Hommy

Posted on

[JCAIGC]Batch add video materials

ADD_VIDEOS API Interface Documentation

📋 Table of Contents

🔧 Interface Information 

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

Function Description

Batch add video materials. This interface is used to add multiple video materials to CapCut draft at once, supporting mask effects, transition animations, volume control, and other advanced features. It is suitable for multi-track video editing, picture-in-picture effects, split-screen effects, 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
videos array ✅ - Video material list, supports adding multiple videos at once

Video Object Structure 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "videos": [
    {
      "video_url": "https://example.com/video1.mp4",
      "duration": 10.0,
      "position": "center",
      "scale": 1.0,
      "rotation": 0,
      "opacity": 1.0,
      "start_time": 0,
      "volume": 1.0,
      "speed": 1.0,
      "mask": {
        "type": "circle",
        "size": 0.8,
        "feather": 0.2
      },
      "animation": {
        "in": "fade_in",
        "out": "fade_out",
        "duration": 1.0
      },
      "transition": {
        "type": "slide_left",
        "duration": 0.5
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Video Parameter Description

Parameter Name Type Required Default Value Description
video_url string ✅ - Video file URL, supports MP4, MOV, AVI, MKV formats
duration number ❌ Auto Video display duration (seconds)
position string ❌ "center" Video position
scale number ❌ 1.0 Video scale, range: 0.1-5.0
rotation number ❌ 0 Video rotation angle, range: -360 to 360 degrees
opacity number ❌ 1.0 Video transparency, range: 0.0-1.0
start_time number ❌ 0 Start display time (seconds)
volume number ❌ 1.0 Volume, range: 0.0-2.0
speed number ❌ 1.0 Playback speed, range: 0.25-4.0
mask object ❌ null Mask effect configuration
animation object ❌ null Animation effect configuration
transition object ❌ null Transition effect configuration

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

Mask Effect Configuration

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

Animation Effect Configuration

Animation Type Description Application Scenario
fade_in Fade in Natural transition
fade_out Fade out Natural transition
scale_in Scale in Highlight effect
scale_out Scale out Highlight effect
slide_left Slide in from left Dynamic entry
slide_right Slide in from right Dynamic entry
slide_up Slide in from bottom Dynamic entry
slide_down Slide in from top Dynamic entry
rotate Rotation Dynamic effect
bounce Bounce Lively effect

Transition Effect Configuration

Transition Type Description Application Scenario
slide_left Slide left Smooth transition
slide_right Slide right Smooth transition
slide_up Slide up Smooth transition
slide_down Slide down Smooth transition
fade Fade Natural transition
dissolve Dissolve Creative transition
wipe_left Wipe left Dynamic transition
wipe_right Wipe right Dynamic transition

Speed Parameter Description

Speed Range Effect Description
0.25 - 0.5 Slow motion, suitable for detail display
0.5 - 0.9 Slow playback, suitable for emphasizing content
1.0 Normal speed, standard playback
1.1 - 2.0 Fast playback, suitable for time-lapse effects
2.1 - 4.0 High speed, suitable for fast-forward effects

Volume Parameter Description

Volume Range Effect Description
0.0 Mute, no sound
0.1 - 0.3 Low volume, suitable for background music
0.4 - 0.7 Medium volume, suitable for normal dialogue
0.8 - 1.0 High volume, suitable for main content
1.1 - 2.0 Extra high volume, suitable for special needs

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 videos, 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. Basic video addition 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "videos": [
      {
        "video_url": "https://example.com/main_video.mp4",
        "duration": 30.0,
        "position": "center",
        "scale": 1.0,
        "volume": 1.0,
        "start_time": 0
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

2. Picture-in-picture effect 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "videos": [
      {
        "video_url": "https://example.com/background.mp4",
        "duration": 60.0,
        "position": "center",
        "scale": 1.0,
        "volume": 0.3,
        "start_time": 0
      },
      {
        "video_url": "https://example.com/overlay.mp4",
        "duration": 20.0,
        "position": "bottom_right",
        "scale": 0.3,
        "opacity": 0.9,
        "volume": 1.0,
        "start_time": 10.0,
        "mask": {
          "type": "circle",
          "size": 0.8,
          "feather": 0.2
        },
        "animation": {
          "in": "scale_in",
          "out": "fade_out",
          "duration": 1.0
        }
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

3. Split-screen effect 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "videos": [
      {
        "video_url": "https://example.com/left_video.mp4",
        "duration": 30.0,
        "position": {
          "x": 25,
          "y": 50,
          "unit": "%"
        },
        "scale": 0.5,
        "volume": 1.0,
        "start_time": 0
      },
      {
        "video_url": "https://example.com/right_video.mp4",
        "duration": 30.0,
        "position": {
          "x": 75,
          "y": 50,
          "unit": "%"
        },
        "scale": 0.5,
        "volume": 1.0,
        "start_time": 0
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

JavaScript Example 

// Add video function
const addVideos = async (draftUrl, videoList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_videos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      videos: videoList
    })
  });
  return response.json();
};

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

  const videoList = [
    {
      video_url: "https://example.com/background.mp4",
      duration: 60.0,
      position: "center",
      scale: 1.0,
      volume: 0.3,
      start_time: 0
    },
    {
      video_url: "https://example.com/overlay.mp4",
      duration: 20.0,
      position: "bottom_right",
      scale: 0.3,
      opacity: 0.9,
      volume: 1.0,
      start_time: 10.0,
      mask: {
        type: "circle",
        size: 0.8,
        feather: 0.2
      },
      animation: {
        in: "scale_in",
        out: "fade_out",
        duration: 1.0
      }
    }
  ];

  const result = await addVideos(draftUrl, videoList);
  console.log('Videos added successfully:', result);
})();
Enter fullscreen mode Exit fullscreen mode

Python Example 

import requests

def add_videos(draft_url, video_list):
    """Batch add video materials"""
    response = requests.post(
        'https://api.assets.jcaigc.cn/openapi/capcut-mate/v1/add_videos',
        headers={'Content-Type': 'application/json'},
        json={
            "draft_url": draft_url,
            "videos": video_list
        }
    )
    return response.json()

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

video_list = [
    {
        "video_url": "https://example.com/left_video.mp4",
        "duration": 30.0,
        "position": {
            "x": 25,
            "y": 50,
            "unit": "%"
        },
        "scale": 0.5,
        "volume": 1.0,
        "start_time": 0
    },
    {
        "video_url": "https://example.com/right_video.mp4",
        "duration": 30.0,
        "position": {
            "x": 75,
            "y": 50,
            "unit": "%"
        },
        "scale": 0.5,
        "volume": 1.0,
        "start_time": 0
    }
]

result = add_videos(draft_url, video_list)
print(f"Videos 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 videos parameter must be an array videos parameter format error Ensure videos is an array type
400 video_url cannot be empty Video URL cannot be empty Provide a valid video_url
400 Invalid duration value Duration value is out of range Duration should be greater than 0
400 Invalid scale value Scale value is out of range Scale should be between 0.1-5.0
400 Invalid rotation value Rotation angle is out of range Rotation should be between -360 to 360 degrees
400 Invalid opacity value Transparency value is out of range Opacity should be between 0.0-1.0
400 Invalid volume value Volume value is out of range Volume should be between 0.0-2.0
400 Invalid speed value Speed value is out of range Speed should be between 0.25-4.0
400 Invalid mask type Mask type error Use preset mask types
400 Invalid animation type Animation type error Use preset animation types
400 Invalid transition type Transition type error Use preset transition types
404 Draft does not exist Specified draft cannot be found Confirm the draft URL is correct and exists
500 Video addition failed Internal service error Contact technical support or try again later
503 Service unavailable System under maintenance Try again later

Notes

  1. Video Format: Support MP4, MOV, AVI, MKV formats, MP4 recommended
  2. Video Size: It is recommended that single video files do not exceed 500MB for better processing speed
  3. Duration Setting: Set appropriate duration to ensure complete video content display
  4. Position Layout: Choose appropriate positions to achieve the desired visual effect
  5. Scale Control: Adjust the scale appropriately to achieve the best visual effect
  6. Volume Control: Adjust volume appropriately to achieve the best audio effect
  7. Speed Adjustment: Use speed adjustment moderately to achieve special effects
  8. Mask Effects: Use mask effects appropriately to create creative visual effects
  9. Animation Effects: Choose appropriate animation effects to enhance visual appeal
  10. Transition Effects: Use transition effects appropriately to achieve smooth transitions
  11. Network Stability: Adding videos requires network support, ensure stable network connection

Workflow

  1. Verify draft_url and videos parameters
  2. Validate video_url format and accessibility
  3. Apply position, scale, rotation, and transparency settings
  4. Configure volume and speed parameters
  5. Apply mask, animation, and transition effects
  6. Generate video material objects
  7. Apply videos to the draft
  8. Update draft configuration file
  9. Return updated draft information

Next Steps

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

  • add_images: Add image materials
  • add_audios: Add audio materials
  • add_captions: Add subtitles
  • add_effects: Add special effects
  • add_masks: Add mask 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)