Skip to main content

​
Music Webhook Callbacks

Instead of polling the Query Music Detail endpoint, you can provide a callback_url when submitting music generation tasks to receive automatic notifications when generation completes.

​
How It Works

  1. Submit with callback URL: Include a callback_url parameter in your music generation request
  2. Task processing: Vidgo API processes your music generation task
  3. Receive notification: When the task status becomes finished or failed, Vidgo API sends a POST request to your callback URL
  4. Process result: Your server receives the complete task data including generated files

​
Callback Request

When a task completes, Vidgo API will send a POST request to your callback URL:

​
Request Headers

Content-Type: application/json

​
Request Body Structure

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [...],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}
The files array content varies depending on which model created the task. See Response Fields below for details.

​
Response Fields (files data)

The files array content varies depending on which model created the task.
ModelFieldTypeDescription
generate-music, extend-music, upload-and-cover-audio, upload-and-extend-audio, add-instrumental, add-vocals, replace-sectionaudio_idstringUnique identifier for the audio file
閳?audio_urlstringDirect download URL for the audio file
閳?image_urlstringCover image URL
閳?titlestringTrack title
閳?tagsstringStyle tags
閳?durationnumberAudio duration in seconds
閳?promptstringGeneration prompt used
get-timestamped-lyricstimestampe_lyricsstringLyrics with timestamps
generate-lyricstitlestringLyrics title
閳?textstringComplete lyrics content
boost-music-stylestylestringEnhanced music style
convert-to-wavwav_urlstringURL to converted WAV file
separate-vocalsseparate_vocalsstring (JSON)JSON string containing separated audio URLs. See details
upload-and-separate-vocalsvocal_removalstring (JSON)JSON string containing separated stem URLs. See details
stem-splitstem_splitstring (JSON)JSON string containing full stem separation URLs. See details
generate-music-covergenerate_coverstring (JSON)JSON string containing generated cover images. See details
generate-personapersona_idstringGenerated persona identifier
create-music-videovideo_urlstringGenerated video URL

​
JSON Field Details

​
separate-vocals

separate_vocals fields:
  • vocal_url - URL to the extracted vocal track
  • instrumental_url - URL to the instrumental track

​
upload-and-separate-vocals

vocal_removal fields:
  • bass - URL to the bass track
  • drums - URL to the drums track
  • piano - URL to the piano track
  • guitar - URL to the guitar track
  • vocals - URL to the vocals track
  • other - URL to other audio elements

​
stem-split

stem_split fields:
  • backing_vocals_url - URL to backing vocals
  • bass_url - URL to bass track
  • brass_url - URL to brass instruments
  • drums_url - URL to drums track
  • fx_url - URL to sound effects
  • guitar_url - URL to guitar track
  • keyboard_url - URL to keyboard track
  • percussion_url - URL to percussion track
  • strings_url - URL to strings track
  • synth_url - URL to synthesizer track
  • vocal_url - URL to main vocals
  • woodwinds_url - URL to woodwinds track

​
generate-music-cover

generate_cover is a JSON array containing cover image objects:
  • file_url - URL to the generated cover image
  • file_type - File type (e.g., “image”)

​
Callback Examples

​
Music Generation (generate-music, extend-music, etc.)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "audio_id": "62e4542a-73be-44e1-b397-7716ee7505c6",
        "audio_url": "https://storage.vidgo.ai/audio/8FDN1I7M7Q68DDG8/audio_62e4542a.mp3",
        "image_url": "https://storage.vidgo.ai/audio/8FDN1I7M7Q68DDG8/cover_62e4542a.jpeg",
        "title": "Peaceful Piano Meditation",
        "tags": "Classical",
        "duration": 240.0,
        "prompt": ""
      },
      {
        "audio_id": "8e755734-a840-4c13-beac-b9f1044979ca",
        "audio_url": "https://storage.vidgo.ai/audio/8FDN1I7M7Q68DDG8/audio_8e755734.mp3",
        "image_url": "https://storage.vidgo.ai/audio/8FDN1I7M7Q68DDG8/cover_8e755734.jpeg",
        "title": "Peaceful Piano Meditation",
        "tags": "Classical",
        "duration": 130.0,
        "prompt": ""
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
Timestamped Lyrics (get-timestamped-lyrics)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "timestampe_lyrics": "[00:00.00] First line of lyrics\n[00:05.23] Second line of lyrics"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
Generated Lyrics (generate-lyrics)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "title": "Peaceful Piano Meditation",
        "text": "Peaceful Piano Meditation lyrics content..."
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
Music Style Enhancement (boost-music-style)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "style": "Enhanced music style result"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
WAV Conversion (convert-to-wav)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "wav_url": "https://storage.vidgo.ai/audio/8FDN1I7M7Q68DDG8/output.wav"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
Vocal Separation (separate-vocals)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "separate_vocals": "{\"vocal_url\": \"https://storage.vidgo.ai/audio/vocals.mp3\", \"instrumental_url\": \"https://storage.vidgo.ai/audio/instrumental.mp3\"}"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
Upload & Separate Vocals (upload-and-separate-vocals)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "vocal_removal": "{\"bass\": \"https://storage.vidgo.ai/audio/bass.mp3\", \"drums\": \"https://storage.vidgo.ai/audio/drums.mp3\", \"piano\": \"https://storage.vidgo.ai/audio/piano.mp3\", \"guitar\": \"https://storage.vidgo.ai/audio/guitar.mp3\", \"vocals\": \"https://storage.vidgo.ai/audio/vocals.mp3\", \"other\": \"https://storage.vidgo.ai/audio/other.mp3\"}"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
Stem Split (stem-split)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "stem_split": "{\"backing_vocals_url\": \"\", \"bass_url\": \"\", \"brass_url\": \"\", \"drums_url\": \"\", \"fx_url\": \"\", \"guitar_url\": \"\", \"keyboard_url\": \"\", \"percussion_url\": \"\", \"strings_url\": \"\", \"synth_url\": \"\", \"vocal_url\": \"\", \"woodwinds_url\": \"\"}"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
Music Cover Image (generate-music-cover)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "generate_cover": "[{\"file_url\": \"https://storage.vidgo.ai/audio/cover_1.png\", \"file_type\": \"image\"}, {\"file_url\": \"https://storage.vidgo.ai/audio/cover_2.png\", \"file_type\": \"image\"}]"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
Generated Persona (generate-persona)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "persona_id": "persona_abc123"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
Music Video (create-music-video)

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "finished",
    "files": [
      {
        "video_url": "https://storage.vidgo.ai/video/8FDN1I7M7Q68DDG8/music_video.mp4"
      }
    ],
    "created_time": "2025-11-25T08:50:13",
    "error_message": null
  }
}

​
Failed Task

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "failed",
    "files": [],
    "created_time": "2025-11-25T08:50:13",
    "error_message": "The prompt violates our content policy"
  }
}

​
Requirements

Your callback endpoint must meet the following requirements:
  • HTTPS only: Must use HTTPS protocol (HTTP not supported)
  • Maximum URL length: 2048 characters
  • Response timeout: Must respond within 10 seconds
  • Success response: Should return HTTP 200-299 status code
  • No internal IPs: Cannot use private/internal IP addresses (e.g., 192.168.x.x, 10.x.x.x)
  • Public accessibility: Must be publicly accessible from the internet

​
Retry Policy

If your callback endpoint fails to respond or returns an error:
  • Retry attempts: 3 automatic retries
  • Retry delays: After 1 second, 2 seconds, and 4 seconds
  • Final failure: After 3 failed attempts, no further retries are made
If all retry attempts fail, you can still retrieve the results by polling the Query Music Detail endpoint.

​
Security Best Practices

Verify requests: Consider adding a signature verification mechanism to ensure requests are from Vidgo API
Idempotency: Design your webhook handler to be idempotent in case of duplicate deliveries
Async processing: Process the callback asynchronously and return 200 quickly to avoid timeouts
Logging: Log all webhook requests for debugging and monitoring