ADD_VIDEOS API Documentation #

🌐 Language Switch #

中文版 | English

Interface Information #

POST /openapi/capcut-mate/v1/add_videos

Function Description #

Batch add video materials to existing drafts. This interface is a powerful video addition tool that supports batch processing of multiple videos, including time range control, transparency adjustment, mask effects, transition animations, volume control, scaling transformations, and other advanced features. Particularly suitable for creating complex multi-video combination scenes, such as picture-in-picture effects, video splicing, transition animations, etc.

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",
  "video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1024,\"height\":1024,\"start\":0,\"end\":5000000,\"duration\":5000000,\"mask\":\"circle\",\"transition\":\"fade\",\"transition_duration\":500000,\"volume\":0.8}]",
  "scene_timelines": [{"start":0,"end":2500000}],
  "alpha": 0.5,
  "scale_x": 1.0,
  "scale_y": 1.0,
  "transform_x": 100,
  "transform_y": 200
}

Parameter Description #

video_infos Array Structure #

scene_timelines Array Structure #

Parameter Details #

Time Parameters #

• start: Start time of the video on the timeline, unit microseconds (1 second = 1,000,000 microseconds)
• end: End time of the video on the timeline, unit microseconds
• duration: Total duration of the video file, used for material creation (optional parameter, defaults to end-start if not provided)
• Playback Duration: Actual playback duration = end - start

Transparency Parameters #

• alpha: Global transparency, applied to all added videos
  • 1.0 = Fully opaque
  • 0.5 = Semi-transparent
  • 0.0 = Fully transparent
  • Range: 0.0 - 1.0

Scaling Parameters #

• scale_x/scale_y: Scaling ratios in X/Y axis directions
• 1.0 = Original size, 0.5 = Half size, 2.0 = Double size
• Recommended range: 0.1 - 5.0

Position Parameters #

• transform_x/transform_y: Position offsets in X/Y axis directions, unit pixels
• Positive values move right/down, negative values move left/up
• Canvas center as origin

Mask Types #

Supported mask types (all optional, default is no mask):

• circle - Circular mask effect
• heart - Heart-shaped mask
• star - Star-shaped mask
• rectangle - Rectangular mask
• linear - Linear gradient mask
• mirror - Mirror reflection mask

Transition Effects #

• transition: Transition effect name
• transition_duration: Transition duration
  • Minimum: 100,000 microseconds (0.1 seconds)
  • Maximum: 2,500,000 microseconds (2.5 seconds)
  • Recommended: 500,000 microseconds (0.5 seconds)

Volume Control #

• volume: Video volume size
  • 1.0 = Original volume
  • 0.5 = Half volume
  • 0.0 = Mute
  • Range: 0.0 - 1.0

Video Speed Change (scene_timelines) #

• scene_timelines: Scene timeline array for video speed change, corresponds one-to-one with video_infos
  • Each item contains start and end fields (microseconds)
  • Speed calculation: speed = (video.end - video.start) / (scene_timeline.end - scene_timeline.start)
  • Example: If video timeline is 0-2000000 (2 seconds) and scene_timeline is 0-1000000 (1 second), the video will play at 2x speed
  • If not provided, video plays at normal speed (1.0x)

Speed Change Example:

// Original video: 2 seconds on timeline (0-2000000)
// To make it 2x speed (play in 1 second):
{
  "video_infos": "[{\"video_url\":\"...\", \"start\":0, \"end\":2000000}]",
  "scene_timelines": "[{\"start\":0, \"end\":1000000}]"
}
// Result: Video plays at 2x speed, actual playback duration is 1 second

Response Format #

Success Response (200) #

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "track_id": "video-track-uuid",
  "video_ids": ["video1-uuid", "video2-uuid", "video3-uuid"],
  "segment_ids": ["segment1-uuid", "segment2-uuid", "segment3-uuid"]
}

Response Field Description #

Usage Examples #

cURL Examples #

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": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000,\"duration\":10000000}]"
  }'

2. Batch Adding Multiple Videos #

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000,\"duration\":10000000},{\"video_url\":\"https://assets.jcaigc.cn/video2.mp4\",\"width\":1280,\"height\":720,\"start\":5000000,\"end\":10000000,\"duration\":8000000}]",
    "alpha": 0.8
  }'

3. Video with Mask and Transition #

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1024,\"height\":1024,\"start\":0,\"end\":5000000,\"duration\":10000000,\"mask\":\"circle\",\"transition\":\"fade\",\"transition_duration\":500000,\"volume\":0.8}]",
    "alpha": 1.0,
    "scale_x": 1.2,
    "scale_y": 1.2
  }'

4. 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": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/main.mp4\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":10000000,\"duration\":15000000},{\"video_url\":\"https://assets.jcaigc.cn/pip.mp4\",\"width\":640,\"height\":360,\"start\":2000000,\"end\":8000000,\"duration\":10000000}]",
    "transform_x": 300,
    "transform_y": -200,
    "scale_x": 0.3,
    "scale_y": 0.3
  }'

5. Video with Speed Change (2x Speed) #

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"start\":0,\"end\":2000000}]",
    "scene_timelines": [{"start":0, "end":1000000}]
  }'

6. Multiple Videos with Different Speeds #

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"start\":0,\"end\":3000000},{\"video_url\":\"https://assets.jcaigc.cn/video2.mp4\",\"start\":3000000,\"end\":6000000}]",
    "scene_timelines": [{"start":0, "end":1500000},{"start":0, "end":4000000}]
  }'
# video1: 3000000/1500000 = 2x speed
# video2: 3000000/4000000 = 0.75x speed (slow motion)

Error Code Description #

Notes #

1. JSON Format: video_infos must be a valid JSON string
2. Time Unit: All time parameters use microseconds (1 second = 1,000,000 microseconds)
3. Video Format: Ensure video file format is supported (e.g., MP4, AVI, etc.)
4. File Size: Large video files may affect processing speed
5. Network Access: Video URL must be accessible
6. Mask Limitation: Only predefined mask types are supported
7. Transition Limitation: Transition duration has fixed range limitations
8. Performance Consideration: Batch adding a large number of videos may affect performance
9. Speed Change: scene_timelines is an object array, length should match video_infos array length

Workflow #

1. Validate required parameters (draft_url, video_infos)
2. Parse video_infos JSON string
3. Validate parameter configuration for each video
4. Obtain and decrypt draft content
5. Create video track
6. Add video segments to track
7. Apply transparency, scaling and position transformation
8. Add mask and transition effects
9. Set volume
10. Save and encrypt draft
11. Return processing result

Related Interfaces #

• Create Draft
• Add Audios
• Add Images
• Save Draft
• Generate Video