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
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:
separate_vocal Type Callback
split_stem Type Callback
Vocal Separation Failed Callback
{
"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
Callback status code indicating task processing result: Status Code Description 200 Success - Vocal separation completed 400 Bad Request - Invalid source audio or parameter error 401 Unauthorized - Invalid API key 429 Insufficient Credits - Account credit balance insufficient 500 Server Error - Please retry later
Status message providing detailed status description
Task ID, consistent with the taskId returned when you submitted the task
Vocal separation result information, returned on success. Fields vary based on separation type
separate_vocal Type Fields
data.vocal_removal_info.origin_url
Original audio file URL
data.vocal_removal_info.vocal_url
Separated vocal audio file URL
data.vocal_removal_info.instrumental_url
Separated instrumental audio file URL (no vocals)
split_stem Type Fields
data.vocal_removal_info.origin_url
Original audio file URL
data.vocal_removal_info.vocal_url
Separated vocal audio file URL
data.vocal_removal_info.backing_vocals_url
Separated backing vocals audio file URL
data.vocal_removal_info.drums_url
Separated drums audio file URL
data.vocal_removal_info.bass_url
Separated bass audio file URL
data.vocal_removal_info.guitar_url
Separated guitar audio file URL
data.vocal_removal_info.keyboard_url
Separated keyboard audio file URL
data.vocal_removal_info.percussion_url
Separated percussion instruments audio file URL
data.vocal_removal_info.strings_url
Separated string instruments audio file URL
data.vocal_removal_info.synth_url
Separated synthesizer audio file URL
data.vocal_removal_info.fx_url
Separated sound effects audio file URL
data.vocal_removal_info.brass_url
Separated brass instruments audio file URL
data.vocal_removal_info.woodwinds_url
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' );
});
from flask import Flask, request, jsonify
import requests
import os
app = Flask( __name__ )
@app.route ( '/vocal-separation-callback' , methods = [ 'POST' ])
def handle_callback ():
data = request.json
code = data.get( 'code' )
msg = data.get( 'msg' )
callback_data = data.get( 'data' , {})
task_id = callback_data.get( 'task_id' )
vocal_info = callback_data.get( 'vocal_removal_info' )
print ( f "Received vocal separation callback: { task_id } , Status: { code } " )
if code == 200 and vocal_info:
# Vocal separation successful
print ( "Vocal separation completed successfully" )
# Determine separation type based on callback content
if vocal_info.get( 'instrumental_url' ):
# separate_vocal type
audio_types = [
( 'original' , vocal_info.get( 'origin_url' )),
( 'vocal' , vocal_info.get( 'vocal_url' )),
( 'instrumental' , vocal_info.get( 'instrumental_url' ))
]
else :
# split_stem type
audio_types = [
( 'original' , vocal_info.get( 'origin_url' )),
( 'vocal' , vocal_info.get( 'vocal_url' )),
( 'backing_vocals' , vocal_info.get( 'backing_vocals_url' )),
( 'drums' , vocal_info.get( 'drums_url' )),
( 'bass' , vocal_info.get( 'bass_url' )),
( 'guitar' , vocal_info.get( 'guitar_url' )),
( 'keyboard' , vocal_info.get( 'keyboard_url' )),
( 'percussion' , vocal_info.get( 'percussion_url' )),
( 'strings' , vocal_info.get( 'strings_url' )),
( 'synth' , vocal_info.get( 'synth_url' )),
( 'fx' , vocal_info.get( 'fx_url' )),
( 'brass' , vocal_info.get( 'brass_url' )),
( 'woodwinds' , vocal_info.get( 'woodwinds_url' ))
]
# Download all separated audio files
for audio_name, audio_url in audio_types:
if audio_url:
try :
response = requests.get(audio_url)
if response.status_code == 200 :
filename = f " { task_id } _ { audio_name } .mp3"
with open (filename, "wb" ) as f:
f.write(response.content)
# Check file size
file_size = os.path.getsize(filename)
print ( f " { audio_name } audio downloaded as { filename } , size: { file_size } bytes" )
except Exception as e:
print ( f " { audio_name } audio download failed: { e } " )
else :
# Task failed
print ( f "Vocal separation failed: { msg } " )
# Handle failure cases...
if code == 400 :
print ( "Invalid source audio or parameter error" )
elif code == 429 :
print ( "Insufficient credits" )
elif code == 500 :
print ( "Server internal error" )
# Return 200 status code to confirm callback received
return jsonify({ 'status' : 'received' }), 200
if __name__ == '__main__' :
app.run( host = '0.0.0.0' , port = 3000 )
<? php
header ( 'Content-Type: application/json' );
// Get POST data
$input = file_get_contents ( 'php://input' );
$data = json_decode ( $input , true );
$code = $data [ 'code' ] ?? null ;
$msg = $data [ 'msg' ] ?? '' ;
$callbackData = $data [ 'data' ] ?? [];
$taskId = $callbackData [ 'task_id' ] ?? '' ;
$vocalInfo = $callbackData [ 'vocal_removal_info' ] ?? null ;
error_log ( "Received vocal separation callback: $taskId , Status: $code " );
if ( $code === 200 && $vocalInfo ) {
// Vocal separation successful
error_log ( "Vocal separation completed successfully" );
// Determine separation type and download corresponding files
if ( isset ( $vocalInfo [ 'instrumental_url' ])) {
// separate_vocal type
$audioTypes = [
'original' => $vocalInfo [ 'origin_url' ] ?? '' ,
'vocal' => $vocalInfo [ 'vocal_url' ] ?? '' ,
'instrumental' => $vocalInfo [ 'instrumental_url' ] ?? ''
];
} else {
// split_stem type
$audioTypes = [
'original' => $vocalInfo [ 'origin_url' ] ?? '' ,
'vocal' => $vocalInfo [ 'vocal_url' ] ?? '' ,
'backing_vocals' => $vocalInfo [ 'backing_vocals_url' ] ?? '' ,
'drums' => $vocalInfo [ 'drums_url' ] ?? '' ,
'bass' => $vocalInfo [ 'bass_url' ] ?? '' ,
'guitar' => $vocalInfo [ 'guitar_url' ] ?? '' ,
'keyboard' => $vocalInfo [ 'keyboard_url' ] ?? '' ,
'percussion' => $vocalInfo [ 'percussion_url' ] ?? '' ,
'strings' => $vocalInfo [ 'strings_url' ] ?? '' ,
'synth' => $vocalInfo [ 'synth_url' ] ?? '' ,
'fx' => $vocalInfo [ 'fx_url' ] ?? '' ,
'brass' => $vocalInfo [ 'brass_url' ] ?? '' ,
'woodwinds' => $vocalInfo [ 'woodwinds_url' ] ?? ''
];
}
// Download all separated audio files
foreach ( $audioTypes as $audioName => $audioUrl ) {
if ( $audioUrl ) {
try {
$audioContent = file_get_contents ( $audioUrl );
if ( $audioContent !== false ) {
$filename = "{ $taskId }_{ $audioName }.mp3" ;
file_put_contents ( $filename , $audioContent );
// Check file size
$fileSize = filesize ( $filename );
error_log ( " $audioName audio downloaded as $filename , size: $fileSize bytes" );
}
} catch ( Exception $e ) {
error_log ( " $audioName audio download failed: " . $e -> getMessage ());
}
}
}
} else {
// Task failed
error_log ( "Vocal separation failed: $msg " );
// Handle failure cases...
if ( $code === 400 ) {
error_log ( "Invalid source audio or parameter error" );
} elseif ( $code === 429 ) {
error_log ( "Insufficient credits" );
} elseif ( $code === 500 ) {
error_log ( "Server internal error" );
}
}
// Return 200 status code to confirm callback received
http_response_code ( 200 );
echo json_encode ([ 'status' => 'received' ]);
?>
Best Practices
Vocal Separation Callback Configuration
Multi-track Management : Organize separated tracks with clear naming conventions
Quality Assessment : Verify separation quality for each track type
Storage Organization : Create folder structures for different separation projects
Batch Processing : Implement efficient batch downloads for multiple tracks
Track Analysis : Analyze separated tracks for remix and production purposes
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:
Verify the source audio quality and mixing
Check if the original track has clear instrument separation
Consider the complexity of the musical arrangement
Test with different source materials to understand limitations
Ensure stable network connection for multiple large file downloads
Implement error handling for partial download failures
Verify all track URLs are accessible and not expired
Monitor download progress for all separated tracks
Plan adequate storage for multiple separated track files
Implement consistent naming conventions for track identification
Consider automated organization based on task IDs
Monitor disk space usage for large separation projects
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.