Music Tasks and Webhooks

Most AI Music routes are asynchronous. Your application should always store the returned taskId, keep polling as a fallback, and treat webhooks as the main completion signal.

Most AI Music routes are asynchronous. Your application should always store the returned taskId, keep polling as a fallback, and treat webhooks as the main completion signal.

Query routes

Route	Purpose
`GET /suno/query/task?taskId={taskId}`	Song generation and cover tasks
`GET /suno/query/lyrics?taskId={taskId}`	Lyrics tasks
`GET /suno/query/vocal-removal?taskId={taskId}`	Stem or vocal-removal tasks
`GET /suno/query/wav?taskId={taskId}`	WAV conversion tasks
`GET /suno/query/mp4?taskId={taskId}`	MV generation tasks
`GET /suno/query/cover?taskId={taskId}`	Cover-art tasks

Music task states

Status	Meaning
`PENDING`	queued
`TEXT_SUCCESS`	text or lyric stage completed
`FIRST_SUCCESS`	first audio finished
`SUCCESS`	full job completed
`CREATE_TASK_FAILED`	task creation failed
`GENERATE_AUDIO_FAILED`	generation failed

Webhook callbacks

All async music routes can call your callBackUrl.

Current callback phases

`callbackType`	Meaning
`text`	text or lyric stage completed
`first`	first audio result is ready
`complete`	full workflow completed

Callback example

{
  "callbackType": "complete",
  "task_id": "5c79****be8e",
  "data": [
    {
      "id": "e231****8cad",
      "audio_url": "https://cdn.example.com/track1.mp3",
      "stream_audio_url": "https://cdn.example.com/stream/track1.mp3",
      "image_url": "https://cdn.example.com/cover1.jpeg",
      "title": "Summer Breeze",
      "tags": "pop, R&B",
      "duration": 91.2
    }
  ]
}

Common AI Music error codes

Code	Meaning
`400`	invalid parameters
`401`	authentication failed
`405`	frequency limit exceeded
`413`	text too long
`429`	quota exhausted
`430`	request rate too high
`455`	system maintenance
`500`	server error

Recommended integration pattern

store every submitted taskId
accept webhook callbacks idempotently
keep polling as a fallback if the webhook is delayed
only mark the asset ready after SUCCESS or the final callback

Practical webhook advice

verify webhook source before trusting the payload
store callback receipts with the same task record you use for polling
keep your callback handler fast and queue heavy post-processing work separately

Music Tasks and Webhooks

On this page