Suno

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:

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:

Authorization: Bearer YOUR_API_KEY

Submit requests also require:

Content-Type: application/json

Copy-paste async quickstart

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

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:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}

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

Poll for result

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

Processing response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "processing",
    "createTime": 1767965610929
  }
}

Success response:

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

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

const payload = JSON.parse(data.resultJson);
const tracks = payload.resultUrls;

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

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.

Request body

Simple mode

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

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

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

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

request_type

string

default:"async"

Result delivery mode. Use async for polling with statusTask, or callback for webhook delivery.

callback_url

string

Required when request_type is callback. Must be a public HTTPS URL that can receive task payloads. See Webhooks.

input

object

required

Suno input parameters.

Show properties

mode

string

required

Suno generation mode. Supported values: V4, V4_5, V4_5ALL, V4_5PLUS, V5, V5_5.

prompt

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.

customMode

boolean

required

Whether to use custom lyrics mode. When true, style and title are required.

instrumental

boolean

required

Whether to generate instrumental music without vocals.

style

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.

title

string

Required when customMode is true. Song title, up to 80 characters.

vocalGender

string

Optional vocal gender hint. Supported values: m for male voice or f for female voice.

styleWeight

number

Optional style weight from 0 to 1.

weirdnessConstraint

number

Optional creativity constraint from 0 to 1.

audioWeight

number

Optional audio weight from 0 to 1.

negativeTags

string

Optional negative tags, up to 200 characters.

Response format

Submit task response

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

code

integer

API status code. 200 means the task was accepted.

message

string

Human-readable status message.

data.taskId

string

Unique task identifier used with the status endpoint.

Status response fields

taskId

string

Unique task identifier.

state

string

Current task state: pending, processing, success, or failed.

resultJson

string

JSON string containing generated track objects. Present when state is success.

lyrics

string

Lyrics or prompt text returned by the upstream result. Present only when available.

failCode

string

Machine-readable failure code. Present when state is failed.

failMsg

string

Human-readable failure message. Present when state is failed.

createTime

integer

Task creation timestamp in Unix milliseconds.

completeTime

integer

Task completion timestamp in Unix milliseconds. Present after completion.

costTime

integer

Processing duration in milliseconds. Present after completion when available.

Parsed resultJson structure:

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

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

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

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.

If you receive 429, slow down requests and retry with backoff. For account-level details, see System APIs.

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 for the full error reference.

Getting Started

Image Models

Video Models

Audio Models

Overview

Endpoint and authentication

Copy-paste async quickstart

Poll for result

Request body

Simple mode

Custom lyrics mode

Instrumental mode

Parameters

Response format

Submit task response

Status response fields

Webhook callback mode

Billing

Latency and polling

Errors and troubleshooting

HTTP errors

Task failure fields

Getting Started

Image Models

Video Models

Audio Models

Documentation Index

​Overview

​Endpoint and authentication

​Copy-paste async quickstart

​Poll for result

​Request body

​Simple mode

​Custom lyrics mode

​Instrumental mode

​Parameters

​Response format

​Submit task response

​Status response fields

​Webhook callback mode

​Billing

​Latency and polling

​Errors and troubleshooting

​HTTP errors

​Task failure fields

​Related links

Overview

Endpoint and authentication

Copy-paste async quickstart

Poll for result

Request body

Simple mode

Custom lyrics mode

Instrumental mode

Parameters

Response format

Submit task response

Status response fields

Webhook callback mode

Billing

Latency and polling

Errors and troubleshooting

HTTP errors

Task failure fields

Related links