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: PoYo AI processes your music generation task
Receive notification: When the task status becomes finished or failed, PoYo AI 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, PoYo AI will send a POST request to your callback URL:

Request Headers

Content-Type: application/json
X-Webhook-Timestamp: 1783680000
X-Webhook-Signature: base64_hmac_sha256_signature

Request Body Structure

{
  "task_id": "8FDN1I7M7Q68DDG8",
  "status": "finished",
  "files": [...],
  "created_time": "2025-11-25T08:50:13",
  "error_message": null
}

The webhook body uses the same task_id, status, files, created_time, and error_message fields as the music detail response body, without the outer code and data wrapper. Webhooks currently omit the detail-only credits_amount and progress fields. The files array content varies by model.

Signature Verification

PoYo signs every music webhook request with HMAC-SHA256. Existing receivers can ignore these headers, but production systems should verify them. Get your webhook HMAC key:

GET /api/api-keys/webhook-secret

Rotate your webhook HMAC key:

POST /api/api-keys/webhook-secret/rotate

Signature rule:

base64(HMAC-SHA256(task_id + "." + timestamp, webhook_hmac_key))

Where:

task_id is the top-level task_id in the callback body
timestamp is the value of X-Webhook-Timestamp
webhook_hmac_key is returned by GET /api/api-keys/webhook-secret

Python Verification

import base64
import hashlib
import hmac
import time


def verify_poyo_webhook(payload, headers, webhook_hmac_key):
    task_id = payload.get("task_id")
    timestamp = headers.get("X-Webhook-Timestamp")
    received_signature = headers.get("X-Webhook-Signature")

    if not task_id or not timestamp or not received_signature:
        return False

    if abs(int(time.time()) - int(timestamp)) > 300:
        return False

    expected_signature = base64.b64encode(
        hmac.new(
            webhook_hmac_key.encode("utf-8"),
            f"{task_id}.{timestamp}".encode("utf-8"),
            hashlib.sha256,
        ).digest()
    ).decode("utf-8")

    return hmac.compare_digest(expected_signature, received_signature)

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
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`audio_url`	string	Direct download URL for the audio file
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`image_url`	string	Cover image URL
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`title`	string	Track title
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`tags`	string	Style tags
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`duration`	number	Audio duration in seconds
`generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section`	`prompt`	string	Generation prompt used
`generate-mashup`, `generate-sounds`	`audio_id`, `audio_url`, `stream_audio_url`, `image_url`, `title`, `tags`, `prompt`, `duration`	mixed	Generated audio fields when available
Standard music results	`model_name`, `source_audio_url`, `source_image_url`, `source_stream_audio_url`	string	Model and derivative source metadata when available
`minimax-music-2.6`	`audio_id`	string	Unique identifier for the generated audio file
`minimax-music-2.6`	`audio_url`	string	Direct download URL for the generated audio file
`minimax-music-2.6`	`title`	string	Track title derived from the submitted prompt
`minimax-music-2.6`	`duration`	number	Audio duration in seconds
`minimax-music-2.6`	`prompt`	string	Original prompt used for generation
`get-timestamped-lyrics`	`timestampe_lyrics`	string	Lyrics with timestamps
`generate-lyrics`	`title`	string	Lyrics title
`generate-lyrics`	`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`	object	Separated audio URLs. See details
`upload-and-separate-vocals`	`vocal_removal`	object	Separated stem URLs. See details
`stem-split`	`stem_split`	object	Full stem separation URLs. See details
`generate-music-cover`	`generate_cover`	array	Generated cover images. See details
`generate-persona`	`persona_id`	string	Generated persona identifier
`create-music-video`	`video_url`	string	Generated video URL
`suno-voice-validate`, `suno-voice-regenerate`	`validate_info`, `voice_status`	string \| null	Verification phrase and current validation state
`suno-voice-generate`	`voice_id`, `voice_status`	string \| null	Generated voice identifier and creation state
`suno-voice-check`	`is_available`	boolean	Whether the generated voice can currently be used
Suno Voice tasks	`error_message`, `error_code`	string/number \| null	Structured error details when available

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
piano_url - URL to piano 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 (for example, image)

Callback Examples

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

{
  "task_id": "8FDN1I7M7Q68DDG8",
  "status": "finished",
  "files": [
    {
      "audio_id": "62e4542a-73be-44e1-b397-7716ee7505c6",
      "audio_url": "https://storage.poyo.ai/audio/8FDN1I7M7Q68DDG8/audio_62e4542a.mp3",
      "image_url": "https://storage.poyo.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.poyo.ai/audio/8FDN1I7M7Q68DDG8/audio_8e755734.mp3",
      "image_url": "https://storage.poyo.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
}

Suno Voice Generate

{"task_id":"POYO_VOICE_TASK","status":"finished","files":[{"voice_status":"success","voice_id":"voice_abc123"}],"created_time":"2026-08-26T10:00:00","error_message":null}

Suno Voice Validate or Regenerate

{"task_id":"POYO_VOICE_VALIDATE_TASK","status":"finished","files":[{"voice_status":"wait_validating","validate_info":"Read the displayed verification phrase clearly."}],"created_time":"2026-08-26T10:00:00","error_message":null}

Suno Voice Check

{"task_id":"POYO_VOICE_CHECK_TASK","status":"finished","files":[{"is_available":true}],"created_time":"2026-08-26T10:01:00","error_message":null}

MiniMax Music 2.6

{
  "task_id": "task-unified-1757165031-uyujaw3d",
  "status": "finished",
  "files": [
    {
      "audio_id": "task-unified-1757165031-uyujaw3d_audio",
      "audio_url": "https://storage.poyo.ai/audios/task-unified-1757165031-uyujaw3d/output.mp3",
      "title": "City pop, 80s retro, groovy synth bass",
      "duration": 0,
      "prompt": "City pop, 80s retro, groovy synth bass"
    }
  ],
  "created_time": "2026-04-15T10:30:00",
  "error_message": null
}

Timestamped Lyrics (get-timestamped-lyrics)

{
  "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)

{
  "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)

{
  "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)

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

Vocal Separation (separate-vocals)

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

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

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

Stem Split (stem-split)

{
  "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)

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

Generated Persona (generate-persona)

{
  "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)

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

Failed Task

{
  "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 30 seconds
Success response: Should return HTTP 200-299 status code
No internal IPs: Cannot use private/internal IP addresses (for example, 192.168.x.x and 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: Up to 5 automatic retries
Retry delays: Exponential backoff, starting at about 60 seconds and capped at 10 minutes
Final failure: After all retry attempts fail, 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: Validate X-Webhook-Timestamp and X-Webhook-Signature before processing callbacks.

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

​Music Webhook Callbacks

​How It Works

​Callback Request

​Request Headers

​Request Body Structure

​Signature Verification

​Python Verification

​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.)

​Suno Voice Generate

​Suno Voice Validate or Regenerate

​Suno Voice Check

​MiniMax Music 2.6

​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

Signature Verification

Python Verification

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.)

Suno Voice Generate

Suno Voice Validate or Regenerate

Suno Voice Check

MiniMax Music 2.6

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