DEV Community

Hommy
Hommy

Posted on

[JCAIGC]Add sticker materials

ADD_STICKER API Interface Documentation

📋 Table of Contents

🔧 Interface Information 

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

Function Description

Add sticker materials. This interface is used to add various sticker materials to CapCut draft, including emoji, decorative stickers, dynamic stickers, and other types. It is suitable for video beautification, emotional expression, content annotation, 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
stickers array ✅ - Sticker material list, supports adding multiple stickers at once

Sticker Object Structure 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "stickers": [
    {
      "sticker_url": "https://example.com/sticker1.png",
      "duration": 5.0,
      "position": "center",
      "scale": 1.0,
      "rotation": 0,
      "opacity": 1.0,
      "start_time": 2.0,
      "animation": "fade_in"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Sticker Parameter Description

Parameter Name Type Required Default Value Description
sticker_url string ✅ - Sticker image URL, supports PNG, JPG, GIF, WebP formats
duration number ✅ - Sticker display duration (seconds), minimum 0.1 seconds
position string ❌ "center" Sticker position
scale number ❌ 1.0 Sticker scale, range: 0.1-5.0
rotation number ❌ 0 Sticker rotation angle, range: -360 to 360 degrees
opacity number ❌ 1.0 Sticker transparency, range: 0.0-1.0
start_time number ❌ 0 Start display time (seconds)
animation string ❌ "none" Animation effect type

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

Animation Effect Types

Animation Type Description Application Scenario
none No animation Static sticker
fade_in Fade in Natural transition
scale_in Scale in Highlight effect
slide_in_left Slide in from left Dynamic entry
slide_in_right Slide in from right Dynamic entry
slide_in_top Slide in from top Dynamic entry
slide_in_bottom Slide in from bottom Dynamic entry
bounce Bounce Lively effect
rotate Rotation Dynamic effect

Sticker Type Description

Sticker Type Format Features
Static sticker PNG, JPG Small size, fast loading
Dynamic sticker GIF, WebP Animated effect, lively
Transparent sticker PNG Support transparency, good fusion
Emoji sticker PNG, GIF Rich expressions, strong interactivity
Decorative sticker PNG, JPG Beautiful appearance, strong decoration

Scale Parameter Description

Scale Range Effect Description
0.1 - 0.3 Very small, suitable for detail decoration
0.3 - 0.6 Small size, suitable for auxiliary elements
0.6 - 1.0 Medium size, suitable for regular stickers
1.0 - 1.5 Large size, suitable for main elements
1.5 - 5.0 Extra large, suitable for special 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 stickers, 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 single sticker 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "stickers": [
      {
        "sticker_url": "https://example.com/smile.png",
        "duration": 3.0,
        "position": "center",
        "scale": 1.0,
        "rotation": 0,
        "opacity": 1.0,
        "start_time": 0,
        "animation": "fade_in"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

2. Add multiple stickers 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "stickers": [
      {
        "sticker_url": "https://example.com/emoji1.png",
        "duration": 2.0,
        "position": "top_left",
        "scale": 0.8,
        "rotation": 15,
        "opacity": 0.9,
        "start_time": 1.0,
        "animation": "bounce"
      },
      {
        "sticker_url": "https://example.com/emoji2.gif",
        "duration": 3.5,
        "position": "bottom_right",
        "scale": 1.2,
        "rotation": -10,
        "opacity": 1.0,
        "start_time": 2.5,
        "animation": "scale_in"
      },
      {
        "sticker_url": "https://example.com/emoji3.png",
        "duration": 1.5,
        "position": "center",
        "scale": 0.6,
        "rotation": 0,
        "opacity": 0.7,
        "start_time": 0.5,
        "animation": "rotate"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

JavaScript Example 

// Add sticker function
const addSticker = async (draftUrl, stickerList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_sticker', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      stickers: stickerList
    })
  });
  return response.json();
};

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

  const stickerList = [
    {
      sticker_url: "https://example.com/smile.png",
      duration: 3.0,
      position: "center",
      scale: 1.0,
      rotation: 0,
      opacity: 1.0,
      start_time: 0,
      animation: "fade_in"
    },
    {
      sticker_url: "https://example.com/heart.gif",
      duration: 2.5,
      position: "top_right",
      scale: 0.8,
      rotation: 15,
      opacity: 0.9,
      start_time: 1.0,
      animation: "bounce"
    }
  ];

  const result = await addSticker(draftUrl, stickerList);
  console.log('Stickers added successfully:', result);
})();
Enter fullscreen mode Exit fullscreen mode

Python Example 

import requests

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

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

sticker_list = [
    {
        "sticker_url": "https://example.com/smile.png",
        "duration": 3.0,
        "position": "center",
        "scale": 1.0,
        "rotation": 0,
        "opacity": 1.0,
        "start_time": 0,
        "animation": "fade_in"
    },
    {
        "sticker_url": "https://example.com/heart.gif",
        "duration": 2.5,
        "position": "top_right",
        "scale": 0.8,
        "rotation": 15,
        "opacity": 0.9,
        "start_time": 1.0,
        "animation": "bounce"
    }
]

result = add_sticker(draft_url, sticker_list)
print(f"Stickers 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 stickers parameter must be an array stickers parameter format error Ensure stickers is an array type
400 sticker_url cannot be empty Sticker URL cannot be empty Provide a valid sticker_url
400 Invalid duration value Duration value is out of range Duration should be greater than 0.1 seconds
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 animation type Animation type error Use preset animation types
404 Draft does not exist Specified draft cannot be found Confirm the draft URL is correct and exists
500 Sticker addition failed Internal service error Contact technical support or try again later
503 Service unavailable System under maintenance Try again later

Notes

  1. Sticker Format: Support PNG, JPG, GIF, WebP formats, PNG recommended for transparent effects
  2. Image Size: It is recommended that sticker images do not exceed 2MB for better loading speed
  3. Duration Setting: Set appropriate duration to ensure the sticker display effect
  4. Position Layout: Choose appropriate positions to avoid blocking important content
  5. Scale Control: Adjust the scale appropriately to achieve the best visual effect
  6. Animation Effects: Choose appropriate animation effects to enhance visual appeal
  7. Transparency Adjustment: Adjust transparency appropriately to achieve better fusion effects
  8. Rotation Angle: Use rotation moderately to increase dynamic effects
  9. Start Time: Set appropriate start time to achieve precise timing control
  10. Network Stability: Adding stickers requires network support, ensure stable network connection

Workflow

  1. Verify draft_url and stickers parameters
  2. Validate sticker_url format and accessibility
  3. Apply position, scale, rotation, and transparency settings
  4. Generate sticker animation effects
  5. Create sticker material objects
  6. Apply stickers to the draft
  7. Update draft configuration file
  8. Return updated draft information

Next Steps

After adding sticker 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
  • 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)