DEV Community

Hommy
Hommy

Posted on

[JCAIGC]Add multiple types of material content

easy_create_material API Documentation

API Overview

API Name: easy_create_material

API Endpoint: POST /openapi/capcut-mate/v1/easy_create_material

Description: Add multiple types of material content to an existing draft, including audio, video, images, and text. This interface can add various media materials to the draft at once, automatically handle material properties such as duration and dimensions, and intelligently manage different types of media tracks. It is one of the core interfaces for video creation.

More Documentation

📖 For more detailed documentation and tutorials, please visit: https://docs.jcaigc.cn

Request Parameters

Request Body (application/json)

Parameter Type Required Default Description
draft_url string Yes - Complete URL of the target draft
audio_url string Yes - Audio file URL, cannot be empty or null
text string No null Text content to be added
img_url string No null Image file URL
video_url string No null Video file URL
text_color string No "#ffffff" Text color (hexadecimal format)
font_size integer No 15 Font size
text_transform_y integer No 0 Text Y-axis position offset

Material Type Description

Material Type Supported Formats Auto Processing Duration Setting
Audio MP3, WAV, AAC Auto-get duration Use audio original duration
Video MP4, AVI, MOV Auto-get properties Fixed duration 5 seconds
Image JPEG, PNG, GIF Auto-get dimensions Default duration 3 seconds
Text UTF-8 text Support style settings Default duration 5 seconds

Request Examples

Add All Types of Materials 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "audio_url": "https://assets.jcaigc.cn/audio.mp3",
  "text": "Hello World",
  "img_url": "https://s.coze.cn/t/JTa5Ne6_liY/",
  "video_url": "https://assets.jcaigc.cn/video.mp4",
  "text_color": "#ff0000",
  "font_size": 20,
  "text_transform_y": 100
}
Enter fullscreen mode Exit fullscreen mode

Add Only Audio and Text 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "audio_url": "https://assets.jcaigc.cn/background_music.mp3",
  "text": "Welcome to watch",
  "text_color": "#0066ff",
  "font_size": 18
}
Enter fullscreen mode Exit fullscreen mode

Simplest Request (Audio Only) 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "audio_url": "https://assets.jcaigc.cn/audio.wav"
}
Enter fullscreen mode Exit fullscreen mode

Response Format

Success Response 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}
Enter fullscreen mode Exit fullscreen mode

Error Response

400 Bad Request - Parameter Validation Failed 

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request parameter validation failed",
    "details": "audio_url cannot be empty"
  }
}
Enter fullscreen mode Exit fullscreen mode

404 Not Found - Draft Does Not Exist 

{
  "error": {
    "code": "DRAFT_NOT_FOUND", 
    "message": "Draft file does not exist",
    "details": "Cannot find the specified draft file"
  }
}
Enter fullscreen mode Exit fullscreen mode

500 Internal Server Error - Material Creation Failed 

{
  "error": {
    "code": "MATERIAL_CREATE_FAILED",
    "message": "Material creation failed", 
    "details": "Error occurred while adding audio material"
  }
}
Enter fullscreen mode Exit fullscreen mode

Error Code Description

Error Code HTTP Status Code Description Solution
VALIDATION_ERROR 400 Request parameter validation failed Check if required parameters are provided and parameter format is correct
DRAFT_NOT_FOUND 404 Draft file does not exist Confirm if the draft URL is correct and if the draft has been deleted
MATERIAL_CREATE_FAILED 500 Material creation failed Check if the material URL is valid and network connection is normal
INVALID_URL 400 URL format is invalid Confirm the provided URL format is correct and accessible

Usage Instructions

Parameter Description

  1. draft_url: Must be a valid CapCut draft URL, format is https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258
  2. audio_url: Required parameter, must provide a valid audio file URL, does not accept empty strings or null values
  3. Optional Materials: text, img_url, video_url are all optional parameters, can be added as needed
  4. Text Style: text_color supports hexadecimal color codes, font_size range recommended 10-50
  5. Position Offset: text_transform_y is used to adjust the vertical position of text in the frame

Material Processing Rules

  1. Audio Processing:

    • Automatically parse audio duration
    • Add to audio track
    • Support multiple audio formats

  2. Video Processing:

    • Fixed display duration 5 seconds
    • Maintain original resolution ratio
    • Add to video track

  3. Image Processing:

    • Default display duration 3 seconds
    • Automatically get image dimensions
    • Add to image track

  4. Text Processing:

    • Default display duration 5 seconds
    • Support color and font size settings
    • Adjustable vertical position

Notes

  • Audio is a required parameter, other material types are optional
  • Material URLs must be publicly accessible, HTTPS protocol is recommended
  • Text color uses standard hexadecimal format (e.g., #ffffff, #000000)
  • All durations are calculated in microseconds internally
  • It is recommended to ensure stable network connection before adding materials

Application Scenarios

  1. Quickly Create Multimedia Content: Add background music, video clips, images, and title text at once
  2. Batch Material Import: Quickly add various types of basic materials to newly created drafts
  3. Template-based Creation: Quickly generate video drafts based on fixed material type templates
  4. Automated Workflow: Batch add preset material content in automated video production workflows

Related Interfaces

Technical Implementation

File Structure 

src/
├── schemas/easy_create_material.py    # Request/response data models
├── service/easy_create_material.py    # Business logic implementation
└── router/v1.py                       # API route definition
Enter fullscreen mode Exit fullscreen mode

Core Logic

  1. Parameter Validation: Validate the validity of draft URL and audio URL
  2. Draft Loading: Parse and load draft file from URL
  3. Material Addition: Add audio, video, image, and text materials by type
  4. Track Management: Automatically manage track allocation for different material types
  5. File Saving: Save the updated draft file

Log Recording

The system will record logs for the following key operations:

  • Draft loading success/failure
  • Detailed process of adding each type of material
  • File saving results
  • Error exception information

Version Information: v1.0

Last Updated: 2024-09-24

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

Top comments (0)