When you submit a task to the vocal and instrument separation API, you can use the callBackUrl parameter to set a callback URL. When the task is completed, the system will automatically push the results to your specified address.

Callback Mechanism Overview

The callback mechanism eliminates the need to poll the API for task status. The system will proactively push task completion results to your server. The callback data structure varies based on the type parameter specified in the request.

Callback Timing

The system will send callback notifications in the following situations:
  • Vocal separation completed
  • Vocal separation task failed
  • Error occurred during task processing
Vocal separation has only one callback stage, but different numbers of separated audio file URLs are provided based on the separation type (separate_vocal or split_stem)

Callback Method

  • HTTP Method: POST
  • Content Type: application/json
  • Timeout: 15 seconds

Callback Request Format

When the task is completed, the system will send a POST request to your callBackUrl in the following format. The callback data structure varies based on the requested type parameter:
{
  "code": 200,
  "msg": "vocal Removal generated successfully.",
  "data": {
    "task_id": "3e63b4cc88d52611159371f6af5571e7",
    "vocal_removal_info": {
      "instrumental_url": "https://file.aiquickdraw.com/s/d92a13bf-c6f4-4ade-bb47-f69738435528_Instrumental.mp3",
      "origin_url": "",
      "vocal_url": "https://file.aiquickdraw.com/s/3d7021c9-fa8b-4eda-91d1-3b9297ddb172_Vocals.mp3"
    }
  }
}

Status Code Description

code
integer
required
Callback status code indicating task processing result:
Status CodeDescription
200Success - Vocal separation completed
400Bad Request - Invalid source audio or parameter error
401Unauthorized - Invalid API key
429Insufficient Credits - Account credit balance insufficient
500Server Error - Please retry later
msg
string
required
Status message providing detailed status description
data.task_id
string
required
Task ID, consistent with the taskId returned when you submitted the task
data.vocal_removal_info
object
Vocal separation result information, returned on success. Fields vary based on separation type

separate_vocal Type Fields

data.vocal_removal_info.origin_url
string
Original audio file URL
data.vocal_removal_info.vocal_url
string
Separated vocal audio file URL
data.vocal_removal_info.instrumental_url
string
Separated instrumental audio file URL (no vocals)

split_stem Type Fields

data.vocal_removal_info.origin_url
string
Original audio file URL
data.vocal_removal_info.vocal_url
string
Separated vocal audio file URL
data.vocal_removal_info.backing_vocals_url
string
Separated backing vocals audio file URL
data.vocal_removal_info.drums_url
string
Separated drums audio file URL
data.vocal_removal_info.bass_url
string
Separated bass audio file URL
data.vocal_removal_info.guitar_url
string
Separated guitar audio file URL
data.vocal_removal_info.keyboard_url
string
Separated keyboard audio file URL
data.vocal_removal_info.percussion_url
string
Separated percussion instruments audio file URL
data.vocal_removal_info.strings_url
string
Separated string instruments audio file URL
data.vocal_removal_info.synth_url
string
Separated synthesizer audio file URL
data.vocal_removal_info.fx_url
string
Separated sound effects audio file URL
data.vocal_removal_info.brass_url
string
Separated brass instruments audio file URL
data.vocal_removal_info.woodwinds_url
string
Separated woodwind instruments audio file URL

Callback Reception Examples

Here are example codes for receiving callbacks in various popular programming languages, supporting both separation types:
const express = require('express');
const fs = require('fs');
const https = require('https');
const app = express();

app.use(express.json());

app.post('/vocal-separation-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received vocal separation callback:', {
    taskId: data.task_id,
    status: code,
    message: msg
  });
  
  if (code === 200 && data.vocal_removal_info) {
    // Vocal separation successful
    const vocalInfo = data.vocal_removal_info;
    console.log('Vocal separation completed successfully');
    
    // Determine separation type and download corresponding files
    let audioTypes = [];
    
    if (vocalInfo.instrumental_url) {
      // separate_vocal type
      audioTypes = [
        { name: 'original', url: vocalInfo.origin_url },
        { name: 'vocal', url: vocalInfo.vocal_url },
        { name: 'instrumental', url: vocalInfo.instrumental_url }
      ];
    } else {
      // split_stem type
      audioTypes = [
        { name: 'original', url: vocalInfo.origin_url },
        { name: 'vocal', url: vocalInfo.vocal_url },
        { name: 'backing_vocals', url: vocalInfo.backing_vocals_url },
        { name: 'drums', url: vocalInfo.drums_url },
        { name: 'bass', url: vocalInfo.bass_url },
        { name: 'guitar', url: vocalInfo.guitar_url },
        { name: 'keyboard', url: vocalInfo.keyboard_url },
        { name: 'percussion', url: vocalInfo.percussion_url },
        { name: 'strings', url: vocalInfo.strings_url },
        { name: 'synth', url: vocalInfo.synth_url },
        { name: 'fx', url: vocalInfo.fx_url },
        { name: 'brass', url: vocalInfo.brass_url },
        { name: 'woodwinds', url: vocalInfo.woodwinds_url }
      ];
    }
    
    // Download all separated audio files
    audioTypes.forEach(audio => {
      if (audio.url) {
        const filename = `${data.task_id}_${audio.name}.mp3`;
        const file = fs.createWriteStream(filename);
        
        https.get(audio.url, (response) => {
          response.pipe(file);
          
          file.on('finish', () => {
            file.close();
            console.log(`${audio.name} audio downloaded as ${filename}`);
          });
        }).on('error', (err) => {
          console.error(`${audio.name} audio download failed:`, err.message);
        });
      }
    });
    
  } else {
    // Task failed
    console.log('Vocal separation failed:', msg);
    
    // Handle failure cases...
    if (code === 400) {
      console.log('Invalid source audio or parameter error');
    } else if (code === 429) {
      console.log('Insufficient credits');
    } else if (code === 500) {
      console.log('Server internal error');
    }
  }
  
  // Return 200 status code to confirm callback received
  res.status(200).json({ status: 'received' });
});

app.listen(3000, () => {
  console.log('Vocal separation callback server running on port 3000');
});

Best Practices

Vocal Separation Callback Configuration

  1. Multi-track Management: Organize separated tracks with clear naming conventions
  2. Quality Assessment: Verify separation quality for each track type
  3. Storage Organization: Create folder structures for different separation projects
  4. Batch Processing: Implement efficient batch downloads for multiple tracks
  5. Track Analysis: Analyze separated tracks for remix and production purposes
  6. Backup Strategy: Maintain backups of both original and separated tracks

Separation-Specific Considerations

  • Separation quality depends on the complexity of the original mix
  • Some instruments may not separate cleanly in all cases
  • Vocal separation works best with clear, well-mixed source material
  • Multiple separated files require significant storage space
  • Processing time varies based on track length and complexity

Troubleshooting

Common issues specific to vocal separation callbacks:

Alternative Solutions

If you cannot use the callback mechanism, you can also use polling:

Poll Separation Results

Use the Get Vocal Separation Details interface to regularly query separation task status. Recommend querying every 30 seconds.