DEV Community

Hommy
Hommy

Posted on • Edited on

【JCAIGC】Batch add audio materials

ADD_AUDIOS API Interface Documentation

📋 Table of Contents

🔧 Interface Information 

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

Function Description

Batch add audio materials. This interface is used to add multiple audio materials to CapCut draft at once, supporting volume adjustment, fade-in and fade-out effects, and other audio processing functions. It is suitable for adding background music, sound effects, voiceovers, and other audio 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
audios array ✅ - Audio material list, supports adding multiple audio files at once

Audio Object Structure 

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "audios": [
    {
      "audio_url": "https://assets.jcaigc.cn/background_music.mp3",
      "volume": 0.8,
      "fade_in": 2000000,
      "fade_out": 3000000,
      "start_time": 0,
      "duration": 60000000
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Audio Parameter Description

Parameter Name Type Required Default Value Description
audio_url string ✅ - Audio file URL, supports MP3, WAV, AAC, and other common formats
volume number ❌ 1.0 Volume size, range: 0.0-2.0, 1.0 is original volume
fade_in number ❌ 0 Fade-in time, unit: microseconds (μs), 1000000μs = 1 second
fade_out number ❌ 0 Fade-out time, unit: microseconds (μs), 1000000μs = 1 second
start_time number ❌ 0 Start time, unit: microseconds (μs), 0 means starting from the beginning
duration number ❌ auto Duration, unit: microseconds (μs), if not set, use the full length of the audio

Audio Format Support

Format Extension Description
MP3 .mp3 Most commonly used compressed audio format
WAV .wav Uncompressed audio, best quality
AAC .aac Advanced Audio Coding, high compression efficiency
M4A .m4a Apple audio format, good compatibility
FLAC .flac Lossless compressed audio format

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 audio 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 single background music 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "audios": [
      {
        "audio_url": "https://assets.jcaigc.cn/background_music.mp3",
        "volume": 0.7,
        "fade_in": 2000000,
        "fade_out": 3000000
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

2. Add multiple audio materials 

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "audios": [
      {
        "audio_url": "https://assets.jcaigc.cn/background_music.mp3",
        "volume": 0.6,
        "fade_in": 2000000,
        "fade_out": 2000000
      },
      {
        "audio_url": "https://assets.jcaigc.cn/sound_effect.mp3",
        "volume": 1.2,
        "start_time": 5000000
      },
      {
        "audio_url": "https://assets.jcaigc.cn/voiceover.mp3",
        "volume": 1.0,
        "start_time": 10000000,
        "duration": 30000000
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

JavaScript Example 

// Add audio material function
const addAudios = async (draftUrl, audioList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_audios', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      audios: audioList
    })
  });
  return response.json();
};

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

  const audioList = [
    {
      audio_url: "https://assets.jcaigc.cn/background_music.mp3",
      volume: 0.7,
      fade_in: 2000000,
      fade_out: 3000000
    },
    {
      audio_url: "https://assets.jcaigc.cn/sound_effect.mp3",
      volume: 1.0,
      start_time: 5000000
    }
  ];

  const result = await addAudios(draftUrl, audioList);
  console.log('Audio added successfully:', result);
})();
Enter fullscreen mode Exit fullscreen mode

Python Example 

import requests

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

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

audio_list = [
    {
        "audio_url": "https://assets.jcaigc.cn/background_music.mp3",
        "volume": 0.8,
        "fade_in": 2000000,
        "fade_out": 2000000
    },
    {
        "audio_url": "https://assets.jcaigc.cn/narration.mp3",
        "volume": 1.0,
        "start_time": 10000000
    }
]

result = add_audios(draft_url, audio_list)
print(f"Audio 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 audios parameter must be an array audios parameter format error Ensure audios is an array type
400 audio_url cannot be empty Audio URL cannot be empty Provide a valid audio_url
400 Invalid volume value Volume value is out of range Volume should be between 0.0-2.0
400 Invalid fade time Fade-in/fade-out time 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 Audio material addition failed Internal service error Contact technical support or try again later
503 Service unavailable System under maintenance Try again later

Notes

  1. Audio Format: Make sure the audio file format is supported, it is recommended to use common formats like MP3, WAV
  2. URL Validity: Audio URL must be accessible, it is recommended to use HTTPS protocol
  3. Volume Control: Volume value of 1.0 is the original volume, less than 1.0 reduces volume, greater than 1.0 amplifies volume
  4. Fade Effects: Fade-in and fade-out effects can make audio transitions smoother
  5. Time Setting: start_time and duration are in microseconds, 1000000 microseconds = 1 second
  6. Network Stability: Adding audio materials requires network support, ensure stable network connection
  7. File Size: It is recommended that a single audio file should not exceed 100MB

Workflow

  1. Verify draft_url and audios parameters
  2. Download and analyze audio files
  3. Apply volume and fade effects settings
  4. Add audio materials to the audio track
  5. Update draft configuration file
  6. Return updated draft information

Next Steps

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

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