> For the complete documentation index, see [llms.txt](https://anyint.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://anyint.gitbook.io/docs/ai-music/tasks-and-webhooks.md).

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

## 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

```json
{
  "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

1. store every submitted `taskId`
2. accept webhook callbacks idempotently
3. keep polling as a fallback if the webhook is delayed
4. 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