callBackUrl parameter to set a callback URL. The system will automatically push the results to your specified address when the task is completed.
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.
Callback Timing
The system will send callback notifications in the following situations:- Vocal separation task completed successfully
- Vocal separation task failed
- Errors occurred during task processing
Callback Method
- HTTP Method: POST
- Content Type: application/json
- Timeout Setting: 15 seconds
Callback Request Format
When the task is completed, the system will send a POST request to yourcallBackUrl based on the separation type you selected. Different separation types correspond to different callback data structures:
separate_vocal Type Callbacks
split_stem Type Callbacks
Status Code Description
Callback status code indicating task processing result:
| Status Code | Description |
|---|---|
| 200 | Success - Request has been processed successfully |
| 500 | Internal Error - Please try again later |
Status message providing detailed status description
Task ID, consistent with the task_id returned when you submitted the task
Vocal separation result information, returned on success. The returned fields depend on the separation type (type parameter)
separate_vocal Type Callback Fields
Instrumental part audio URL (separate_vocal type only)
Original audio URL
Vocal part audio URL
split_stem Type Callback Fields
Original audio URL
Main vocal audio URL
Backing vocals audio URL (split_stem type only)
Drums part audio URL (split_stem type only)
Bass part audio URL (split_stem type only)
Guitar part audio URL (split_stem type only)
Keyboard part audio URL (split_stem type only)
Percussion part audio URL (split_stem type only)
Strings part audio URL (split_stem type only)
Synthesizer part audio URL (split_stem type only)
Effects part audio URL (split_stem type only)
Brass part audio URL (split_stem type only)
Woodwinds part audio URL (split_stem type only)
Callback Reception Examples
Below are example codes for receiving callbacks in popular programming languages:- Node.js
- Python
- PHP
Best Practices
Callback URL Configuration Recommendations
- Use HTTPS: Ensure callback URL uses HTTPS protocol for secure data transmission
- Verify Origin: Verify the legitimacy of the request source in callback processing
- Idempotent Processing: The same task_id may receive multiple callbacks, ensure processing logic is idempotent
- Quick Response: Callback processing should return 200 status code quickly to avoid timeout
- Asynchronous Processing: Complex business logic should be processed asynchronously to avoid blocking callback responses
- Type-based Processing: Handle different audio file structures based on different separation types
- Batch Download: split_stem type produces multiple files, recommend batch downloading and organizing by type
Important Reminders
- Callback URL must be publicly accessible
- Server must respond within 15 seconds, otherwise will be considered timeout
- If 3 consecutive retry attempts fail, the system will stop sending callbacks
- Please ensure the stability of callback processing logic to avoid callback failures due to exceptions
- Vocal separation generated audio file URLs may have time limits, recommend downloading and saving promptly
- Note that some audio part URLs may be empty, certain instrument separations might be empty
- separate_vocal and split_stem types return different fields, please handle corresponding fields based on the type parameter in the request
Troubleshooting
If you are not receiving callback notifications, please check the following:Network Connection Issues
Network Connection Issues
- Confirm callback URL is accessible from public internet
- Check firewall settings to ensure inbound requests are not blocked
- Verify domain name resolution is correct
Server Response Issues
Server Response Issues
- Ensure server returns HTTP 200 status code within 15 seconds
- Check server logs for error messages
- Verify endpoint path and HTTP method are correct
Content Format Issues
Content Format Issues
- Confirm received POST request body is in JSON format
- Check if Content-Type is application/json
- Verify JSON parsing is correct
File Processing Issues
File Processing Issues
- Confirm all audio file URLs are accessible
- Check file download permissions and network connection
- Verify file save path and permissions
- Note that some instrument separation results may be empty
- Note the field differences between separate_vocal and split_stem types
Alternative Solutions
If you cannot use the callback mechanism, you can also use polling:Poll Query Results
Use the Get Vocal Separation Details endpoint to periodically query task status. We recommend querying every 30 seconds.
