DEV Community

Hommy
Hommy

Posted on

【JCAIGC】Batch add image materials

ADD_IMAGES API Interface Documentation

📋 Table of Contents

🔧 Interface Information 

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

Function Description

Batch add image materials. This interface is used to add multiple image materials to CapCut draft at once, supporting transparency, position adjustment, size scaling, rotation angle, and other image processing functions. It is suitable for adding logos, watermarks, stickers, backgrounds, and other image 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
images array ✅ - Image material list, supports adding multiple image files at once

Image Object Structure 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "images": [
    {
      "image_url": "https://assets.jcaigc.cn/logo.png",
      "start_time": 0,
      "duration": 5000000,
      "position": "top_right",
      "scale": 0.3,
      "rotation": 0,
      "opacity": 0.8
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Image Parameter Description

Parameter Name Type Required Default Value Description
image_url string ✅ - Image file URL, supports PNG, JPG, JPEG, GIF, WebP, and other formats
start_time number ❌ 0 Start time, unit: microseconds (μs), 1000000μs = 1 second
duration number ❌ auto Duration, unit: microseconds (μs), if not set, use the full video length
position string ❌ "center" Image position, supports preset positions and custom coordinates
scale number ❌ 1.0 Image scaling ratio, 1.0 is original size
rotation number ❌ 0 Rotation angle, unit: degrees, supports 0-360 degrees
opacity number ❌ 1.0 Transparency, range: 0.0-1.0, 1.0 is completely opaque

Image Format Support

Format Extension Transparency Support Description
PNG .png ✅ Best transparency support, suitable for logos and watermarks
JPG/JPEG .jpg/.jpeg ❌ Common photo format, small file size
GIF .gif ✅ Supports animation, suitable for dynamic stickers
WebP .webp ✅ Modern image format, good compression ratio
SVG .svg ✅ Vector graphics, infinitely scalable
BMP .bmp ❌ Uncompressed bitmap, large file size

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

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 image 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 logo watermark 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "images": [
      {
        "image_url": "https://assets.jcaigc.cn/logo.png",
        "start_time": 0,
        "duration": 60000000,
        "position": "top_right",
        "scale": 0.2,
        "opacity": 0.7
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

2. Add multiple images with different effects 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "images": [
      {
        "image_url": "https://assets.jcaigc.cn/logo.png",
        "start_time": 0,
        "duration": 10000000,
        "position": "top_left",
        "scale": 0.15,
        "opacity": 0.8
      },
      {
        "image_url": "https://assets.jcaigc.cn/sticker.gif",
        "start_time": 5000000,
        "duration": 8000000,
        "position": "bottom_right",
        "scale": 0.4,
        "rotation": 15,
        "opacity": 0.9
      },
      {
        "image_url": "https://assets.jcaigc.cn/background.jpg",
        "start_time": 15000000,
        "duration": 10000000,
        "position": "center",
        "scale": 1.2,
        "opacity": 0.3
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

JavaScript Example 

// Add image material function
const addImages = async (draftUrl, imageList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_images', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      images: imageList
    })
  });
  return response.json();
};

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

  const imageList = [
    {
      image_url: "https://assets.jcaigc.cn/logo.png",
      start_time: 0,
      duration: 60000000,
      position: "top_right",
      scale: 0.2,
      opacity: 0.7
    },
    {
      image_url: "https://assets.jcaigc.cn/sticker.png",
      start_time: 10000000,
      duration: 5000000,
      position: "bottom_left",
      scale: 0.3,
      rotation: 45,
      opacity: 0.9
    }
  ];

  const result = await addImages(draftUrl, imageList);
  console.log('Images added successfully:', result);
})();
Enter fullscreen mode Exit fullscreen mode

Python Example 

import requests

def add_images(draft_url, image_list):
    """Add image materials"""
    response = requests.post(
        'https://api.assets.jcaigc.cn/openapi/capcut-mate/v1/add_images',
        headers={'Content-Type': 'application/json'},
        json={
            "draft_url": draft_url,
            "images": image_list
        }
    )
    return response.json()

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

image_list = [
    {
        "image_url": "https://assets.jcaigc.cn/logo.png",
        "start_time": 0,
        "duration": 60000000,
        "position": "top_right",
        "scale": 0.2,
        "opacity": 0.7
    },
    {
        "image_url": "https://assets.jcaigc.cn/sticker.png",
        "start_time": 10000000,
        "duration": 5000000,
        "position": "bottom_left",
        "scale": 0.3,
        "rotation": 45,
        "opacity": 0.9
    }
]

result = add_images(draft_url, image_list)
print(f"Images 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 images parameter must be an array images parameter format error Ensure images is an array type
400 image_url cannot be empty Image URL cannot be empty Provide a valid image_url
400 Invalid scale value Scaling ratio is out of range Scale should be greater than 0
400 Invalid rotation value Rotation angle is out of range Rotation should be between 0-360 degrees
400 Invalid opacity value Transparency value is out of range Opacity should be between 0.0-1.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 Image material addition failed Internal service error Contact technical support or try again later
503 Service unavailable System under maintenance Try again later

Notes

  1. Image Format: Make sure the image file format is supported, it is recommended to use PNG format for transparency support
  2. URL Validity: Image URL must be accessible, it is recommended to use HTTPS protocol
  3. File Size: It is recommended that a single image file should not exceed 10MB
  4. Transparency Processing: PNG format supports the best transparency effect, suitable for logos and watermarks
  5. Position Layout: Choose appropriate positions to avoid blocking important video content
  6. Scaling Ratio: Adjust the image size appropriately to maintain visual balance
  7. Rotation Angle: Rotation can create dynamic effects, but avoid over-rotation
  8. Network Stability: Adding image materials requires network support, ensure stable network connection

Workflow

  1. Verify draft_url and images parameters
  2. Download and analyze image files
  3. Apply position, scaling, rotation, and transparency settings
  4. Generate image material objects
  5. Add image materials to the image track
  6. Update draft configuration file
  7. Return updated draft information

Next Steps

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

  • add_videos: Add video 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)