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:- MIDI generation task completed successfully
- MIDI generation 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
:
Status Code Description
Callback status code indicating task processing result:
Status Code | Description |
---|---|
200 | Success - MIDI generation completed successfully |
500 | Internal Error - Please try again or contact support |
Status message providing detailed status description
Task ID, consistent with the task_id returned when you submitted the task
MIDI generation result information, returned on success
Success Response Fields
Processing state. Value:
complete
when successfulArray of detected instruments with their MIDI note data
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 (like MIDI file conversion) should be processed asynchronously
- Handle Missing Instruments: Not all instruments may be detected - handle empty or missing instrument arrays gracefully
- Store Raw Data: Save the complete JSON response for future reference and reprocessing
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
- MIDI data is retained for 14 days - download and save promptly if needed long-term
- The number and types of instruments detected depends on audio content
- Note times (start/end) may be strings or numbers - handle both types
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
- Handle both string and number types for timing values
Data Processing Issues
Data Processing Issues
- Some instruments may have empty note arrays
- Not all audio will detect all instrument types
- Verify the original vocal separation used
split_stem
type (notseparate_vocal
) - Check that the source taskId is from a successfully completed separation
Alternative Solutions
If you cannot use the callback mechanism, you can also use polling:Poll Query Results
Use the Get MIDI Generation Details endpoint to periodically query task status. We recommend querying every 10-30 seconds.