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

Submit with callback URL: Include a callback_url parameter in your music generation request
Task processing: Vidgo API processes your music generation task
Receive notification: When the task status becomes finished or failed, Vidgo API sends a POST request to your callback URL
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.

Model	Field	Type	Description
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`audio_id`	string	Unique identifier for the audio file
閳?	`audio_url`	string	Direct download URL for the audio file
閳?	`image_url`	string	Cover image URL
閳?	`title`	string	Track title
閳?	`tags`	string	Style tags
閳?	`duration`	number	Audio duration in seconds
閳?	`prompt`	string	Generation prompt used
`get-timestamped-lyrics`	`timestampe_lyrics`	string	Lyrics with timestamps
`generate-lyrics`	`title`	string	Lyrics title
閳?	`text`	string	Complete lyrics content
`boost-music-style`	`style`	string	Enhanced music style
`convert-to-wav`	`wav_url`	string	URL to converted WAV file
`separate-vocals`	`separate_vocals`	string (JSON)	JSON string containing separated audio URLs. See details
`upload-and-separate-vocals`	`vocal_removal`	string (JSON)	JSON string containing separated stem URLs. See details
`stem-split`	`stem_split`	string (JSON)	JSON string containing full stem separation URLs. See details
`generate-music-cover`	`generate_cover`	string (JSON)	JSON string containing generated cover images. See details
`generate-persona`	`persona_id`	string	Generated persona identifier
`create-music-video`	`video_url`	string	Generated 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

Overview

Image Series

Video Series

Music Series

File Management

Task Management

Account Management

Music Webhook

Music Webhook Callbacks

How It Works

Callback Request

Request Headers

Request Body Structure

Response Fields (files data)

JSON Field Details

separate-vocals

upload-and-separate-vocals

stem-split

generate-music-cover

Callback Examples

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

Timestamped Lyrics (get-timestamped-lyrics)

Generated Lyrics (generate-lyrics)

Music Style Enhancement (boost-music-style)

WAV Conversion (convert-to-wav)

Vocal Separation (separate-vocals)

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

Stem Split (stem-split)

Music Cover Image (generate-music-cover)

Generated Persona (generate-persona)

Music Video (create-music-video)

Failed Task

Requirements

Retry Policy

Security Best Practices

​Music Webhook Callbacks

​How It Works

​Callback Request

​Request Headers

​Request Body Structure

​Response Fields (files data)

​JSON Field Details

​separate-vocals

​upload-and-separate-vocals

​stem-split

​generate-music-cover

​Callback Examples

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

​Timestamped Lyrics (get-timestamped-lyrics)

​Generated Lyrics (generate-lyrics)

​Music Style Enhancement (boost-music-style)

​WAV Conversion (convert-to-wav)

​Vocal Separation (separate-vocals)

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

​Stem Split (stem-split)

​Music Cover Image (generate-music-cover)

​Generated Persona (generate-persona)

​Music Video (create-music-video)

​Failed Task

​Requirements

​Retry Policy

​Security Best Practices

Music Webhook Callbacks

How It Works

Callback Request

Request Headers

Request Body Structure

Response Fields (files data)

JSON Field Details

separate-vocals

upload-and-separate-vocals

stem-split

generate-music-cover

Callback Examples

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

Timestamped Lyrics (get-timestamped-lyrics)

Generated Lyrics (generate-lyrics)

Music Style Enhancement (boost-music-style)

WAV Conversion (convert-to-wav)

Vocal Separation (separate-vocals)

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

Stem Split (stem-split)

Music Cover Image (generate-music-cover)

Generated Persona (generate-persona)

Music Video (create-music-video)

Failed Task

Requirements

Retry Policy

Security Best Practices