> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Music Webhook
> Receive automatic callback notifications when music generation tasks complete
# Music Webhook Callbacks
Instead of polling the [Query Music Detail](/api-manual/music-series/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
```json theme={null}
{
"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](#response-fields-files-data) 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](#separate-vocals) |
| `upload-and-separate-vocals` | `vocal_removal` | string (JSON) | JSON string containing separated stem URLs. [See details](#upload-and-separate-vocals) |
| `stem-split` | `stem_split` | string (JSON) | JSON string containing full stem separation URLs. [See details](#stem-split) |
| `generate-music-cover` | `generate_cover` | string (JSON) | JSON string containing generated cover images. [See details](#generate-music-cover) |
| `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.)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"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
```json theme={null}
{
"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](/api-manual/music-series/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