DEV Community

Hommy
Hommy

Posted on

【JCAIGC】Add subtitle materials

ADD_CAPTIONS API Interface Documentation

📋 Table of Contents

🔧 Interface Information 

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

Function Description

Add subtitle materials. This interface is used to add subtitle content to CapCut draft, supporting custom subtitle text, font, color, position, animation effects, and other attributes. It is suitable for adding explanatory text, titles, dialogue subtitles, and other text 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
captions array ✅ - Subtitle material list, supports adding multiple subtitles at once

Subtitle Object Structure 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "captions": [
    {
      "text": "Hello, welcome to CapCut Mate!",
      "start_time": 0,
      "duration": 3000000,
      "font": "Arial",
      "font_size": 24,
      "color": "#FFFFFF",
      "position": "bottom_center",
      "animation": "fade_in"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Subtitle Parameter Description

Parameter Name Type Required Default Value Description
text string ✅ - Subtitle text content, supports multiple languages and special characters
start_time number ✅ - Start time, unit: microseconds (μs), 1000000μs = 1 second
duration number ✅ - Duration, unit: microseconds (μs), 1000000μs = 1 second
font string ❌ "Arial" Font name, supports common system fonts
font_size number ❌ 20 Font size, range: 10-100
color string ❌ "#FFFFFF" Text color, supports hexadecimal color codes
position string ❌ "bottom_center" Text position, supports preset positions
animation string ❌ "none" Text animation effect

Position Options

Position Value Description
top_left Top left corner
top_center Top center
top_right Top right corner
center_left Center left
center Absolute center
center_right Center right
bottom_left Bottom left corner
bottom_center Bottom center
bottom_right Bottom right corner

Animation Options

Animation Value Description
none No animation
fade_in Fade in
fade_out Fade out
slide_left Slide in from left
slide_right Slide in from right
slide_up Slide in from bottom
slide_down Slide in from top
scale Scale in
rotate Rotate in

Color Support

Format Example Description
Hexadecimal "#FF0000" Red
RGB "rgb(255,0,0)" Red
RGBA "rgba(255,0,0,0.8)" Semi-transparent red
Color Name "red" Red

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 subtitle 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 simple subtitle 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "captions": [
      {
        "text": "Welcome to CapCut Mate!",
        "start_time": 0,
        "duration": 3000000,
        "font": "Arial",
        "font_size": 24,
        "color": "#FFFFFF",
        "position": "bottom_center"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

2. Add multiple subtitles with different styles 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "captions": [
      {
        "text": "Chapter 1: Getting Started",
        "start_time": 0,
        "duration": 5000000,
        "font": "Microsoft YaHei",
        "font_size": 32,
        "color": "#FF6B6B",
        "position": "top_center",
        "animation": "fade_in"
      },
      {
        "text": "This is a demonstration video",
        "start_time": 6000000,
        "duration": 4000000,
        "font": "Arial",
        "font_size": 24,
        "color": "#FFFFFF",
        "position": "bottom_center",
        "animation": "slide_left"
      },
      {
        "text": "Thank you for watching!",
        "start_time": 12000000,
        "duration": 3000000,
        "font": "Arial",
        "font_size": 28,
        "color": "#4ECDC4",
        "position": "center",
        "animation": "scale"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

JavaScript Example 

// Add subtitle material function
const addCaptions = async (draftUrl, captionList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_captions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      captions: captionList
    })
  });
  return response.json();
};

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

  const captionList = [
    {
      text: "Welcome to CapCut Mate!",
      start_time: 0,
      duration: 3000000,
      font: "Arial",
      font_size: 24,
      color: "#FFFFFF",
      position: "bottom_center",
      animation: "fade_in"
    },
    {
      text: "Easy to create wonderful videos",
      start_time: 4000000,
      duration: 3000000,
      font: "Microsoft YaHei",
      font_size: 20,
      color: "#FFD93D",
      position: "bottom_center",
      animation: "slide_up"
    }
  ];

  const result = await addCaptions(draftUrl, captionList);
  console.log('Subtitles added successfully:', result);
})();
Enter fullscreen mode Exit fullscreen mode

Python Example 

import requests

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

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

caption_list = [
    {
        "text": "Welcome to CapCut Mate!",
        "start_time": 0,
        "duration": 3000000,
        "font": "Arial",
        "font_size": 24,
        "color": "#FFFFFF",
        "position": "bottom_center",
        "animation": "fade_in"
    },
    {
        "text": "Create professional videos easily",
        "start_time": 4000000,
        "duration": 3000000,
        "font": "Microsoft YaHei",
        "font_size": 20,
        "color": "#FFD93D",
        "position": "bottom_center",
        "animation": "slide_up"
    }
]

result = add_captions(draft_url, caption_list)
print(f"Subtitles 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 captions parameter must be an array captions parameter format error Ensure captions is an array type
400 text cannot be empty Subtitle text cannot be empty Provide valid subtitle text
400 Invalid time format Time parameter format error Time should be a non-negative number
400 Invalid font size Font size is out of range Font size should be between 10-100
400 Invalid color format Color format error Use valid color format
400 Invalid position value Position parameter error Use preset position values
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 Subtitle material addition failed Internal service error Contact technical support or try again later
503 Service unavailable System under maintenance Try again later

Notes

  1. Text Content: Subtitle text supports multiple languages, special characters, and emojis
  2. Time Setting: start_time and duration are in microseconds, 1000000 microseconds = 1 second
  3. Font Selection: It is recommended to use common system fonts to ensure compatibility
  4. Color Matching: Choose appropriate colors to ensure text is clearly visible
  5. Position Layout: Choose appropriate positions based on video content to avoid blocking important images
  6. Animation Effects: Use animation effects appropriately to enhance visual experience
  7. Duration Control: Ensure subtitle duration matches audio content
  8. Network Stability: Adding subtitle materials requires network support, ensure stable network connection

Workflow

  1. Verify draft_url and captions parameters
  2. Validate subtitle text and time settings
  3. Apply font, color, position, and animation settings
  4. Generate subtitle material objects
  5. Add subtitle materials to the subtitle track
  6. Update draft configuration file
  7. Return updated draft information

Next Steps

After adding subtitle 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_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)