docs.sunoapi.org
language
language
  • 🇺🇸 English
  • 🇨🇳 Chinese
language
language
  • 🇺🇸 English
  • 🇨🇳 Chinese
Support
Suno API
Common APIFile Upload API
Suno API
Common APIFile Upload API
  1. Music Video Generation
  • Suno API Documentation
  • Suno API Quick Start
  • Generate Music
    • Music Generation Callbacks
    • Music Extension Callbacks
    • Upload and Cover Audio Callbacks
    • Upload and Extend Audio Callbacks
    • Add Instrumental Callbacks
    • Add Vocals Callbacks
    • Music Cover Generation Callbacks
    • Replace Music Section Callbacks
    • Generate Music
      POST
    • Extend Music
      POST
    • Upload And Cover Audio
      POST
    • Upload And Extend Audio
      POST
    • Add Instrumental
      POST
    • Add Vocals
      POST
    • Get Music Generation Details
      GET
    • Recovery Audio
      POST
    • Get Recovery Audio Details
      GET
    • Get Timestamped Lyrics
      POST
    • Boost Music Style
      POST
    • Generate Music Cover
      POST
    • Replace Music Section
      POST
    • Get Music Cover Details
      GET
    • Generate Persona
      POST
    • Generate Mashup
      POST
  • Suno Voice
    • Suno Voice Validation Phrase Callbacks
    • Suno Voice Generation Callbacks
    • Suno Voice Regenerate Phrase Callbacks
    • Suno Voice Generate Verification Phrase
    • Suno Voice Get Verification Phrase
    • Suno Voice Create Custom Voice
    • Suno Voice Get Custom Voice Record
    • Suno Voice Regenerate Verification Phrase
    • Suno Voice Check Availability
  • Generate Lyrics
    • Lyrics Generation Callbacks
    • Generate Lyrics
    • Get Lyrics Generation Details
  • Generate Sounds
    • Generate Sounds
  • WAV Conversion
    • WAV Format Conversion Callbacks
    • Convert to WAV Format
    • Get WAV Conversion Details
  • Vocal Removal
    • Audio Separation Callbacks
    • MIDI Generation Callbacks
    • Vocal & Instrument Stem Separation
    • Get Audio Separation Details
    • Generate MIDI from Audio
    • Get MIDI Generation Details
  • Music Video Generation
    • Music Video Generation Callbacks
    • Create Music Video
      POST
    • Get Music Video Details
      GET
  • Generate Speech
    • Generate Speech
  1. Music Video Generation

Music Video Generation Callbacks

When music video generation tasks are completed, the system will send results to your provided callback URL via POST request
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 task completed successfully
Music video 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 your callBackUrl in the following format:
Success Callback
Failure Callback
{
  "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 - Parameter error, unsupported audio file format, etc.
451Download Failed - Unable to download source audio file
500Server Error - Please try again 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 file download URL, returned on success

Callback Reception Examples#

Here are example codes for receiving callbacks in popular programming languages:
Node.js
Python
PHP

Best Practices#

Callback URL Configuration Recommendations#

1.
Use HTTPS: Ensure your callback URL uses HTTPS protocol for secure data transmission
2.
Verify Source: Verify the legitimacy of the request source in callback processing
3.
Idempotent Processing: The same taskId may receive multiple callbacks, ensure processing logic is idempotent
4.
Quick Response: Callback processing should return a 200 status code as quickly as possible to avoid timeout
5.
Asynchronous Processing: Complex business logic should be processed asynchronously to avoid blocking callback response
6.
Video Processing: Video file download and processing should be done in asynchronous tasks to avoid blocking callback response

Important Reminders#

Callback URL must be a publicly accessible address
Server must respond within 15 seconds, otherwise it will be considered a timeout
If 3 consecutive retries fail, the system will stop sending callbacks
Please ensure the stability of callback processing logic to avoid callback failures due to exceptions
Generated video file URLs may have time limits, recommend downloading and saving promptly
MP4 video files are large, pay attention to storage space and download time
Ensure sufficient disk space to save video files
Video generation may take longer, please be patient for callback notifications

Troubleshooting#

If you do not receive callback notifications, please check the following:
Network Connection Issues
Server Response Issues
Content Format Issues
Video Processing Issues

Alternative Solution#

If you cannot use the callback mechanism, you can also use polling:
Poll Query Results
Use the get music video details endpoint to regularly query task status. We recommend querying every 30 seconds.
Previous
Get MIDI Generation Details
Next
Create Music Video
Built with