> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno

> AI music generation API for vocal and instrumental song creation

## Overview

Suno generates complete music tracks from a text description or structured lyrics. Use this page when you are ready to call the API after trying Suno in the APIXO playground.

| Capability               | Value                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| Model ID                 | `suno`                                                                                         |
| Output                   | Audio tracks with cover images                                                                 |
| Delivery                 | Async polling or webhook callback                                                              |
| Supported modes          | `V4`, `V4_5`, `V4_5ALL`, `V4_5PLUS`, `V5`, `V5_5`                                              |
| Non-custom prompt length | 1-500 characters                                                                               |
| Custom prompt length     | `V4`: 1-3000 characters; `V4_5`, `V4_5ALL`, `V4_5PLUS`, `V5`, `V5_5`: 1-5000 characters        |
| Custom style length      | `V4`: up to 200 characters; `V4_5`, `V4_5ALL`, `V4_5PLUS`, `V5`, `V5_5`: up to 1000 characters |

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint                           | Purpose                               |
| ------ | ---------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/suno`               | Submit a music generation task        |
| `GET`  | `/statusTask/suno?taskId={taskId}` | Poll task status and retrieve results |

All requests require your APIXO API key:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

This minimal request submits a simple text-to-music task and returns a `taskId`.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/suno" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "V5_5",
      "prompt": "upbeat pop song about a summer road trip",
      "customMode": false,
      "instrumental": false
    }
  }'
```

Successful response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
```

Save the `taskId`; you need it to poll for the final result.

## Poll for result

```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/suno?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Processing response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "processing",
    "createTime": 1767965610929
  }
}
```

Success response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[{\"audio_url\":\"https://file.apixo.ai/track1.mp3\",\"image_url\":\"https://file.apixo.ai/cover1.jpg\"},{\"audio_url\":\"https://file.apixo.ai/track2.mp3\",\"image_url\":\"https://file.apixo.ai/cover2.jpg\"}]}",
    "lyrics": "[Verse 1]\nRolling down the highway...",
    "createTime": 1767965610929,
    "completeTime": 1767965700929,
    "costTime": 90000
  }
}
```

Failed response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "PromptInvalid",
    "failMsg": "Prompt is invalid or rejected by provider",
    "createTime": 1767965610929,
    "completeTime": 1767965620132,
    "costTime": 9203
  }
}
```

Parse `resultJson` after `state` becomes `success`:

```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const tracks = payload.resultUrls;

for (const track of tracks) {
  console.log(track.audio_url, track.image_url);
}
```

<Warning>
  Suno `resultJson` contains `resultUrls` as an array of objects. Each item can include `audio_url` for the generated MP3 and `image_url` for the cover image. Do not parse it as a plain string URL array.
</Warning>

## Request body

### Simple mode

Use `customMode: false` when you want Suno to create the song from a short description.

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "V5_5",
    "prompt": "upbeat pop song about a summer road trip",
    "customMode": false,
    "instrumental": false
  }
}
```

### Custom lyrics mode

Use `customMode: true` when you want to provide lyrics, style, and title.

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "V4_5PLUS",
    "prompt": "[Verse 1]\nWalking down an empty street\nEchoes of your laughter sweet\n\n[Chorus]\nI miss you more than words can say",
    "customMode": true,
    "instrumental": false,
    "style": "orchestral, emotional, film score",
    "title": "Dawn of Hope",
    "vocalGender": "f",
    "styleWeight": 0.6,
    "weirdnessConstraint": 0.2,
    "audioWeight": 0.5,
    "negativeTags": "noise, distortion"
  }
}
```

### Instrumental mode

Set `instrumental: true` when you want music without vocals.

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "V4_5PLUS",
    "prompt": "cinematic orchestral track with gentle piano and strings",
    "customMode": true,
    "instrumental": true,
    "style": "orchestral, cinematic, ambient",
    "title": "Peaceful Morning",
    "styleWeight": 0.7
  }
}
```

## Parameters

<ParamField body="request_type" type="string" default="async">
  Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
</ParamField>

<ParamField body="callback_url" type="string">
  Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive task payloads. See [Webhooks](/api-reference/webhooks).
</ParamField>

<ParamField body="input" type="object" required>
  Suno input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" required>
      Suno generation mode. Supported values: `V4`, `V4_5`, `V4_5ALL`, `V4_5PLUS`, `V5`, `V5_5`.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Song description or lyrics. Must be a non-empty string. In non-custom mode, supports 1-500 characters. In custom mode, `V4` supports up to 3000 characters and `V4_5`, `V4_5ALL`, `V4_5PLUS`, `V5`, and `V5_5` support up to 5000 characters.
    </ParamField>

    <ParamField body="customMode" type="boolean" required>
      Whether to use custom lyrics mode. When `true`, `style` and `title` are required.
    </ParamField>

    <ParamField body="instrumental" type="boolean" required>
      Whether to generate instrumental music without vocals.
    </ParamField>

    <ParamField body="style" type="string">
      Required when `customMode` is `true`. Music style description. `V4` supports up to 200 characters; `V4_5`, `V4_5ALL`, `V4_5PLUS`, `V5`, and `V5_5` support up to 1000 characters.
    </ParamField>

    <ParamField body="title" type="string">
      Required when `customMode` is `true`. Song title, up to 80 characters.
    </ParamField>

    <ParamField body="vocalGender" type="string">
      Optional vocal gender hint. Supported values: `m` for male voice or `f` for female voice.
    </ParamField>

    <ParamField body="styleWeight" type="number">
      Optional style weight from `0` to `1`.
    </ParamField>

    <ParamField body="weirdnessConstraint" type="number">
      Optional creativity constraint from `0` to `1`.
    </ParamField>

    <ParamField body="audioWeight" type="number">
      Optional audio weight from `0` to `1`.
    </ParamField>

    <ParamField body="negativeTags" type="string">
      Optional negative tags, up to 200 characters.
    </ParamField>
  </Expandable>
</ParamField>

## Response format

### Submit task response

`POST /generateTask/suno` returns a task ID when the task is accepted:

<ResponseField name="code" type="integer">
  API status code. `200` means the task was accepted.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="data.taskId" type="string">
  Unique task identifier used with the status endpoint.
</ResponseField>

### Status response fields

<ResponseField name="taskId" type="string">
  Unique task identifier.
</ResponseField>

<ResponseField name="state" type="string">
  Current task state: `pending`, `processing`, `success`, or `failed`.
</ResponseField>

<ResponseField name="resultJson" type="string">
  JSON string containing generated track objects. Present when `state` is `success`.
</ResponseField>

<ResponseField name="lyrics" type="string">
  Lyrics or prompt text returned by the upstream result. Present only when available.
</ResponseField>

<ResponseField name="failCode" type="string">
  Machine-readable failure code. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="failMsg" type="string">
  Human-readable failure message. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="createTime" type="integer">
  Task creation timestamp in Unix milliseconds.
</ResponseField>

<ResponseField name="completeTime" type="integer">
  Task completion timestamp in Unix milliseconds. Present after completion.
</ResponseField>

<ResponseField name="costTime" type="integer">
  Processing duration in milliseconds. Present after completion when available.
</ResponseField>

Parsed `resultJson` structure:

```json theme={null}
{
  "resultUrls": [
    {
      "audio_url": "https://file.apixo.ai/track1.mp3",
      "image_url": "https://file.apixo.ai/cover1.jpg"
    },
    {
      "audio_url": "https://file.apixo.ai/track2.mp3",
      "image_url": "https://file.apixo.ai/cover2.jpg"
    }
  ]
}
```

| Field in each item | Type   | Description                  |
| ------------------ | ------ | ---------------------------- |
| `audio_url`        | string | Generated MP3 audio file URL |
| `image_url`        | string | Generated cover image URL    |

## Webhook callback mode

Use callback mode when your backend should receive task payloads automatically instead of polling.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/suno" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/webhooks/apixo",
    "input": {
      "mode": "V5_5",
      "prompt": "warm acoustic song about coming home",
      "customMode": false,
      "instrumental": false
    }
  }'
```

Only parse `resultJson` when the callback payload has `state: "success"`. See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior.

## Billing

Suno is billed per generation request. The current public APIXO catalog lists Suno at `$0.12 / use`.

| Model      | Route     | APIXO price | Unit    |
| ---------- | --------- | ----------- | ------- |
| Suno V5    | Exclusive | `$0.12`     | per use |
| Suno V5\_5 | Exclusive | `$0.12`     | per use |

For current pricing, see [Pricing](https://apixo.ai/pricing).

## Latency and polling

Actual latency may vary by prompt complexity, selected mode, provider queue, and current load.

| Workflow              | Typical generation time | Recommended first poll  | Poll interval |
| --------------------- | ----------------------- | ----------------------- | ------------- |
| Suno music generation | 60s-90s                 | 45s after task creation | 5s-10s        |

<Tip>
  For production workloads, use callback mode to reduce polling traffic. Result URLs are stored for 15 days by default; account-level storage settings may change the retention period.
</Tip>

If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/api-reference/system).

## Errors and troubleshooting

### HTTP errors

| Code  | Meaning                                                                               | What to do                                                       |
| ----- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `400` | Missing required parameter, invalid parameter type, invalid value, or length exceeded | Fix the request before retrying                                  |
| `401` | Missing or invalid API key                                                            | Check the `Authorization` header                                 |
| `402` | Insufficient balance                                                                  | Add balance before retrying                                      |
| `422` | Billing calculation failed                                                            | Contact support if the model should be available on your account |
| `429` | Rate limit or concurrency limit reached                                               | Retry with exponential backoff                                   |
| `500` | Server error or unknown task failure                                                  | Retry with backoff                                               |
| `502` | Upstream provider or network error                                                    | Retry with backoff                                               |
| `504` | Upstream timeout                                                                      | Retry or use callback mode for long-running jobs                 |

### Task failure fields

When a task reaches `state: "failed"`, inspect `failCode` and `failMsg` in the status response.

| Fail code example                               | Meaning                                               | What to do                                                                   |
| ----------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- |
| `PromptInvalid`                                 | Prompt was rejected or malformed                      | Rewrite the prompt or lyrics                                                 |
| `SensitiveContent` / `SensitiveContentDetected` | Prompt or output was flagged by safety checks         | Change the prompt, lyrics, or style                                          |
| `MissingParameter`                              | The upstream provider reported missing required data  | Check `mode`, `prompt`, `customMode`, `instrumental`, and custom-mode fields |
| `RateLimited` / `RateLimitExceeded`             | Provider-side rate limit                              | Retry with backoff                                                           |
| `Timeout`                                       | Provider timeout                                      | Retry later or use callback mode                                             |
| `Unknown error`                                 | The failure did not match a known provider error rule | Retry with backoff; contact support if it repeats                            |

See [Error Codes](/api-reference/errors) for the full error reference.

## Related links

* [Generation API Overview](/models)
* [Generate Task](/api-reference/generate-task)
* [Status Task](/api-reference/status-task)
* [Webhooks](/api-reference/webhooks)
* [Error Codes](/api-reference/errors)
* [Parameter Specification](/api-reference/parameters)
* [Routing Strategies](/concepts/routing-strategies)
* [Pricing](https://apixo.ai/pricing)