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.
Callback Timing
The system will send callback notifications in the following situations:- Music video generation completed
- Music video generation task failed
- Error occurred during task processing
Music video generation has only one callback stage, providing the MP4 video download URL upon completion
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 yourcallBackUrl
in the following format:
Status Code Description
Callback status code indicating task processing result:
Status Code | Description |
---|---|
200 | Success - Music video generation 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
Generated MP4 video download URL (returned on success)
Callback Reception Examples
Here are example codes for receiving callbacks in various popular programming languages:- Node.js
- Python
- PHP
Best Practices
Music Video Callback Configuration
- File Size Management: Prepare for larger file downloads as videos are significantly bigger than audio
- Storage Planning: Ensure adequate storage space for MP4 video files
- Download Optimization: Use streaming downloads for large video files to avoid memory issues
- Quality Verification: Verify video file integrity and playback after download
- Metadata Handling: Maintain video metadata and track association with original audio
- Backup Strategy: Implement backup procedures for generated video content
Video-Specific Considerations
- Video files are much larger than audio files, requiring more storage and bandwidth
- Download times can be significantly longer depending on video length and quality
- Ensure stable network connectivity for large file transfers
- Video generation may take longer than audio processing
- Consider implementing progress tracking for video downloads
- Video URLs may have shorter expiration times due to storage costs
Troubleshooting
Common issues specific to music video generation callbacks:Download and Storage Issues
Download and Storage Issues
- Verify adequate storage space for video files
- Check network stability for large file downloads
- Implement chunked downloading for better reliability
- Monitor download progress and implement retry mechanisms
Video Quality and Format
Video Quality and Format
- Confirm the source audio quality meets video generation requirements
- Verify that the generated MP4 plays correctly in different players
- Check video resolution and quality settings
- Test video compatibility across different devices and platforms
Performance Optimization
Performance Optimization
- Implement asynchronous video processing to avoid blocking
- Consider background downloading for large video files
- Monitor server resources during video processing
- Plan for longer processing and download times compared to audio
Source Audio Requirements
Source Audio Requirements
- Ensure source audio meets minimum quality requirements
- Verify that the audio ID and task ID are valid and accessible
- Check if the source audio has sufficient content for video generation
- Confirm that audio metadata is properly preserved in the video
Alternative Solutions
If you cannot use the callback mechanism, you can also use polling:Poll Video Results
Use the Get Music Video Details interface to regularly query video generation task status. Recommend querying every 45 seconds due to longer processing times.