Generating music

Basic generation

Send a POST request to /api/generate with a plain-language description of the music you want. Suno always produces two variations per request.

curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A popular heavy metal song about war, sung by a deep-voiced male singer, slowly and melodiously. The lyrics depict the sorrow of people after the war.",
    "make_instrumental": false,
    "wait_audio": false
  }'

Request fields

prompt

string

required

A natural-language description of the music you want to generate. Suno uses this to write lyrics and choose a style automatically.

make_instrumental

boolean

When true, the generated track has no vocals. Defaults to false.

model

string

The Suno model to use. Defaults to chirp-v3-5 (the DEFAULT_MODEL constant). Pass a different model string to target a specific version.

wait_audio

boolean

When false (default), the request returns immediately with status "submitted". When true, the server waits up to 100 seconds for generation to finish before responding. See Polling for completion below.

The AudioInfo response

Both /api/generate and /api/get return an array of AudioInfo objects — one per clip.

[
  {
    "id": "a1b2c3d4-...",
    "title": "War's Lament",
    "image_url": "https://cdn.suno.ai/image/a1b2c3d4....jpeg",
    "lyric": "In the fields where silence reigns...",
    "audio_url": "https://cdn.suno.ai/a1b2c3d4....mp3",
    "video_url": "https://cdn.suno.ai/a1b2c3d4....mp4",
    "created_at": "2024-03-15T10:30:00.000Z",
    "model_name": "chirp-v3-5",
    "gpt_description_prompt": "A popular heavy metal song about war...",
    "prompt": "In the fields where silence reigns...",
    "status": "streaming",
    "type": "gen",
    "tags": "heavy metal, male vocalist, slow",
    "negative_tags": null,
    "duration": "180.5",
    "error_message": null
  }
]

Field	Type	Description
`id`	string	Unique identifier for the clip. Use this to poll for status or extend the track.
`title`	string \| null	Title assigned by Suno.
`image_url`	string \| null	URL to the generated cover art.
`lyric`	string \| null	The full lyrics text.
`audio_url`	string \| null	Direct URL to the MP3 audio file. Populated once `status` is `"streaming"` or `"complete"`.
`video_url`	string \| null	URL to a video version of the clip.
`created_at`	string	ISO 8601 timestamp of when the clip was created.
`model_name`	string	The model used, e.g. `chirp-v3-5`.
`gpt_description_prompt`	string \| null	The original natural-language prompt sent to the generation API.
`prompt`	string \| null	The lyric text used in the final generation.
`status`	string	Current state of the clip. See status values below.
`type`	string \| null	Internal clip type (e.g. `"gen"`).
`tags`	string \| null	Genre and style tags applied to the generation.
`negative_tags`	string \| null	Styles that were excluded from the generation.
`duration`	string \| null	Duration of the audio in seconds.
`error_message`	string \| null	Human-readable error detail when `status` is `"error"`.

Status values

Status	Meaning
`submitted`	Request accepted; generation has not started yet.
`queued`	Clip is waiting in Suno’s generation queue.
`streaming`	Audio is being written; the file is already playable via `audio_url`.
`complete`	Generation finished; the full audio file is available.
`error`	Generation failed. Check `error_message` for details.

Polling for completion

By default (wait_audio: false) the API returns immediately. The status will be "submitted" and audio_url will be empty. You need to poll /api/get until the audio is ready.

Async (recommended)
Synchronous

Pass wait_audio: false and poll manually. This is the recommended approach because generation can take 30–90 seconds and you avoid holding a connection open.

import time
import requests

base_url = 'http://localhost:3000'

def get_audio_information(audio_ids):
    url = f"{base_url}/api/get?ids={audio_ids}"
    response = requests.get(url)
    return response.json()

# ids from the generate response
ids = f"{data[0]['id']},{data[1]['id']}"
print(f"ids: {ids}")

for _ in range(60):
    result = get_audio_information(ids)
    if result[0]["status"] == 'streaming':
        print(f"{result[0]['id']} ==> {result[0]['audio_url']}")
        print(f"{result[1]['id']} ==> {result[1]['audio_url']}")
        break
    time.sleep(5)

Poll every 3–5 seconds. Stop when status is "streaming" or "complete". If status becomes "error", read error_message from the response.

Pass wait_audio: true to have the server block and return only when generation finishes (or after a 100-second timeout).

curl

curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A calm acoustic folk song about the sea",
    "make_instrumental": false,
    "wait_audio": true
  }'

The response is the same AudioInfo array but with audio_url already populated.

Synchronous mode holds an HTTP connection open for up to 100 seconds. Some deployment environments (e.g., Vercel Serverless Functions on the free plan) have shorter timeout limits. Use async polling in production.

Default model

When you omit the model field, the API uses chirp-v3-5 — the value of the DEFAULT_MODEL constant defined in src/lib/SunoApi.ts. Pass a different string to target another model version.

Error handling

HTTP status	Meaning	What to do
`200`	Success	Read the `AudioInfo` array.
`402`	Payment required — account is out of credits	Top up your Suno credits or rotate to another account.
`503`	Network error — could not reach Suno’s API	Check your internet connection and retry with exponential back-off.
`500`	Internal server error	Check the server logs. The response body includes an `error` field with details.

When a 402 is returned, the response body is {"error": "Payment required"} or a detail string from Suno. Use GET /api/get_limit to check remaining credits before generating in bulk.

Get Started

Configuration

Guides

Basic generation

Request fields

The AudioInfo response

Status values

Polling for completion

Default model

Error handling

Build docs developers (and LLMs) love

Get Started

Configuration

Guides

​Basic generation

​Request fields

​The AudioInfo response

​Status values

​Polling for completion

​Default model

​Error handling

Build docs developers (and LLMs) love

Basic generation

Request fields

The AudioInfo response

Status values

Polling for completion

Default model

Error handling