Suno API Integration Guide

Read This Before You Integrate

This guide complements the parameter tables on the Suno model API pages. The API page is still the source of truth for request fields, field types, and endpoint examples, but this document explains the business rules that are harder to understand from the schema alone.

• Use the API tab on the Suno model page for exact field definitions and example requests.
• Use this guide for mode selection, field combination rules, callback handling, and multi-step flows.
• If you are integrating Suno into a production workflow, read this guide once before writing code.

What Usually Trips Teams Up

1. Create Song is not a single mode. In practice, there are 4 common request combinations, and the required fields are different in each one.
2. Extend also has 2 modes. Whether the result should continue as vocal or instrumental depends on how you send prompt.
3. A full-song flow can involve multiple APIs. In many cases you first extend a song and only then run concat.
4. A callback is not enough by itself to mark the task as successful. You still need to inspect the task-level state and the result payload.

Typical Workflow

A common Suno integration flow looks like this:

1. Call the create task endpoint for the Suno model you need.
2. Store the returned taskId.
3. Wait for the callBackUrl webhook or poll the task query endpoint.
4. For standard generation, expect 2 song variants in many cases.
5. If you need to continue an existing song, run Extend.
6. If you need a merged full-length song after extension, run Concat on the extended result.

1. The 4 Create Song Modes

The original source documents describe 4 creation patterns. The most common integration mistake is assuming some fields can simply be omitted when they actually need to be sent as empty strings.

1.1 Vocal Song from Description

Use this mode when the user gives you a natural-language description of the song they want.

• prompt is the song description.
• title must be an empty string.
• style must be an empty string.
• customMode / custom must be false.
• instrumental must be false.

Example:

1{
2  "input": {
3    "prompt": "A happy and uplifting pop song",
4    "title": "",
5    "style": "",
6    "customMode": false,
7    "instrumental": false
8  }
9}

1.2 Instrumental Song from Description

This mode is similar to the previous one, except that the output should not contain vocals.

• prompt is still a description, not lyrics.
• title should be an empty string.
• style should be an empty string.
• customMode / custom must be false.
• instrumental must be true.

Example:

1{
2  "input": {
3    "prompt": "A bright cinematic synthwave track for a night drive",
4    "title": "",
5    "style": "",
6    "customMode": false,
7    "instrumental": true
8  }
9}

1.3 Custom Vocal Song

Use this mode when you want to control lyrics, style, and title directly.

• prompt contains the lyrics or lyric draft.
• title is required.
• style is required.
• customMode / custom must be true.
• instrumental must be false.

Based on the source material:

• prompt should not exceed 3000 characters.
• style should not exceed 200 characters.

Example:

1{
2  "input": {
3    "prompt": "Write heartfelt lyrics about a summer romance by the sea",
4    "title": "Summer Love",
5    "style": "Warm pop, catchy, radio-friendly",
6    "customMode": true,
7    "instrumental": false
8  }
9}

1.4 Custom Instrumental Song

This is another frequent source of bugs.

• prompt should be an empty string.
• title is required.
• style is required.
• customMode / custom must be true.
• instrumental must be true.

Example:

1{
2  "input": {
3    "prompt": "",
4    "title": "Night Drive",
5    "style": "Synthwave, cinematic, neon atmosphere",
6    "customMode": true,
7    "instrumental": true
8  }
9}

2. The 2 Extend Modes

Extend is used when you already have a generated Suno song and want to continue it from a specific timestamp.

The fields that matter most are:

• audio_id
• continue_at
• title
• style
• prompt

2.1 Extend with Vocals

If the continuation should remain a vocal song:

• prompt should contain the continuation lyrics or vocal guidance.
• title should have a value.
• style should have a value.
• continue_at tells the system from which second the original song should continue.

Example:

1{
2  "input": {
3    "audio_id": "song audio id",
4    "style": "pop",
5    "title": "Extended Song Title",
6    "prompt": "Continue with a new chorus and a longer outro",
7    "continue_at": 60
8  }
9}

2.2 Extend Instrumental Music

If the continuation should stay instrumental:

• prompt should be an empty string.
• title should have a value.
• style should have a value.
• The system distinguishes instrumental vs. vocal continuation based on whether prompt is empty.

Example:

1{
2  "input": {
3    "audio_id": "song audio id",
4    "style": "pop",
5    "title": "Extended Song Title",
6    "prompt": "",
7    "continue_at": 60
8  }
9}

3. What Concat Is For

Concat is used after extension when you want a merged full song rather than only the newly extended segment.

Key points:

• The audio_id you pass here is usually the audio_id returned by the extended result.
• Concat merges the extension back with the original track into a complete song.
• If your business only needs the extension segment itself, you may not need this step.

Example:

1{
2  "input": {
3    "audio_id": "8c9f6a88-672b-4b7c-93e0-31dbfdf42349"
4  }
5}

4. How Task Querying Should Work

Whether you are generating, extending, or concatenating, the create call usually returns a task identifier first.

You then have two ways to get the final result:

1. Provide callBackUrl and wait for the webhook.
2. Do not provide a callback URL and poll the task query endpoint yourself.

Recommended approach:

• Use callBackUrl for backend production workflows.
• Keep polling as a backup for dashboards, debugging, or reconciliation jobs.
• Avoid building a production workflow that depends only on frontend polling.

5. Which Callback States You Should Actually Check

This is the part many users miss.

5.1 ApiPass Task-Level State

In the current ApiPass callback examples, the key task-level state is usually in data.state:

• success: the task completed successfully
• fail: the task failed

Typical success callback:

1{
2  "code": 200,
3  "data": {
4    "taskId": "task_abc123xyz",
5    "state": "success",
6    "completeTime": 1755599644000,
7    "costTime": 45000,
8    "createTime": 1755599599000,
9    "model": "suno/generate",
10    "resultJson": {
11      "data": [
12        {
13          "id": "audio_001",
14          "audio_url": "https://cdn.apipass.dev/results/task_abc123xyz_0_audio.mp3",
15          "image_url": "https://cdn.apipass.dev/results/task_abc123xyz_0_cover.jpeg",
16          "duration": 180.5,
17          "title": "Summer Love",
18          "style": "Pop"
19        }
20      ]
21    }
22  },
23  "msg": "Task completed successfully."
24}

Typical failure callback:

1{
2  "code": 501,
3  "data": {
4    "taskId": "task_abc123xyz",
5    "state": "fail",
6    "failCode": "GENERATION_FAILED",
7    "failMsg": "Music generation failed due to content policy violation"
8  },
9  "msg": "Task failed."
10}

In production, a safe minimum is:

• Treat the task as successful only when code === 200 and data.state === "success".
• Treat data.state === "fail" as a hard failure branch.
• Persist failCode and failMsg for troubleshooting.
• Do not assume that receiving a webhook automatically means success.

5.2 Suno Result-Level Status

In the source documents, each audio object often has its own status field, for example:

• complete

That means you should distinguish:

• data.state for task-level completion
• resultJson.data[].status for each returned audio item

If your business consumes both generated variants, process the array item by item instead of assuming there is only one result.

5.3 The callbackType in the Source Documents

The source documents also show:

• callbackType: "complete"

You can treat that as a helpful secondary signal, but the safer approach is still:

1. Check data.state
2. Parse resultJson.data
3. Validate each result item before moving to the next business step

6. Recommended Fields to Store

If you want a stable integration, store at least the following:

• taskId
• model
• state
• failCode
• failMsg
• audio_id
• audio_url
• image_url
• duration
• title
• style
• status
• completeTime
• the raw callback JSON

This will make retries, reconciliation, support investigations, and callback replays much easier later.

7. Common Mistakes

7.1 Omitting Fields That Should Be Empty Strings

Some Suno modes do not want a missing field. They want an explicitly empty string. The most common cases are:

• title in description mode
• style in description mode
• prompt in custom instrumental mode

7.2 Mixing Description Mode with Custom Mode

If you already have direct lyrics, title, and style, use custom mode. If you only have a natural-language idea of the song, use description mode.

7.3 Reversing the Extend prompt Logic

• Vocal extension: prompt should contain content
• Instrumental extension: prompt should be an empty string

7.4 Marking the Task as Successful as Soon as a Webhook Arrives

That is not enough. At minimum, verify:

• code
• data.state
• whether the result array exists
• whether each result item contains the IDs and URLs your workflow needs

8. Recommended Implementation Order

If you are integrating Suno into a real product, the safest order is:

1. Build Create Song plus Query / Callback handling first.
2. Make sure success and failure callbacks are stored correctly.
3. Add Extend.
4. Add Concat only after the earlier stages are stable.

This is much safer than trying to launch every Suno branch at once.