Skip to main content
When you submit a task to the music video generation 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.

​
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 your callBackUrl in the following format: 
{
  "code": 200,
  "msg": "MP4 generated successfully.",
  "data": {
    "task_id": "taskId_774b9aa0422f",
    "video_url": "https://example.com/videos/video_847715e66259.mp4"
  }
}

​
Status Code Description

​
code
integer
required
Callback status code indicating task processing result:
Status CodeDescription
200Success - Music video generation 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.video_url
string
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
const express = require('express');
const fs = require('fs');
const https = require('https');
const app = express();

app.use(express.json());

app.post('/video-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received music video callback:', {
    taskId: data.task_id,
    status: code,
    message: msg
  });
  
  if (code === 200 && data.video_url) {
    // Video generation successful
    console.log(`Music video ready: ${data.video_url}`);
    
    // Download video file
    downloadVideoFile(data.video_url, data.task_id);
    
  } else {
    // Task failed
    console.log('Music video generation 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' });
});

function downloadVideoFile(url, taskId) {
  const filename = `video_${taskId}.mp4`;
  const file = fs.createWriteStream(filename);
  
  https.get(url, (response) => {
    response.pipe(file);
    
    file.on('finish', () => {
      file.close();
      console.log(`Video file downloaded: ${filename}`);
    });
  }).on('error', (err) => {
    console.error('Video download failed:', err.message);
  });
}

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

​
Best Practices

​
Music Video Callback Configuration

  1. File Size Management: Prepare for larger file downloads as videos are significantly bigger than audio
  2. Storage Planning: Ensure adequate storage space for MP4 video files
  3. Download Optimization: Use streaming downloads for large video files to avoid memory issues
  4. Quality Verification: Verify video file integrity and playback after download
  5. Metadata Handling: Maintain video metadata and track association with original audio
  6. 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:
  • 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
  • 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
  • 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
  • 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.