Suno API documentation overview

Updated 2026-09-18 · Suno-API team

Register with an email address and you can create an API key. A generation call costs ¥0.6, returns 2 songs, and covers MP3/WAV downloads, cover songs, Extend, stems and voice cloning. Base URL: https://www.suno-api.io.

This page lists the models that are currently available, every generation and editing endpoint, how billing works and the recommended order to read everything in. If you are integrating for the first time, read it top to bottom; the 401/403/429 troubleshooting entries are here too.

Quick answers

How do I get an API key? Register with an email address, open the console, go to token management and create a token. No phone number and no bank card required.

What does a call cost? A generation call costs ¥0.6 and returns 2 songs. Status queries, WAV, timestamped lyrics and prompt suggestions are free.

Which models are supported? suno-v6 (default), suno-v6-wild and suno-v6-mini. v5.5 and older standard generation models are retired; existing work is unaffected.

What is the base URL? https://www.suno-api.io, with the header Authorization: Bearer YOUR_API_KEY.

Models currently available

The customer-facing models for standard song generation are suno-v6, suno-v6-wild and suno-v6-mini. When model is omitted, suno-v6 is used.

The standard models suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 and suno-v5-5 are retired. Historical tasks may still show those names; that is historical data, not a sign that the model can be used for new requests. Stems are the exception — see Stems (vocal/accompaniment separation) API.

Authentication

Every public API-key endpoint uses the same headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Base URL:

https://www.suno-api.io

General parameter conventions

• A number in the request body must be a JSON number, not a percentage string. An intensity of 50% is written 0.5, never 50 or 50%.
• A boolean must be true or false. Do not send true, false, 0 or 1 as substitutes.
• Fields marked "no" may be omitted entirely. When you are unsure what a parameter does, leave it out and let the service use its default behaviour; do not send an empty string, null or 0 in place of "not sent", because 0 is a valid value for some numeric fields.
• Field names are spelling-sensitive. Each endpoint page lists the recommended field and the compatible aliases; send them exactly as the parameter table shows. Where the docs say snake_case and camelCase are both accepted, do not send both at once.
• Every duration field ending in _s or Seconds is measured in seconds and accepts decimals. Unix timestamps are described separately, including whether they are seconds or milliseconds.
• An ID starting with pending: is a platform placeholder, not a real song ID. Use it only where an endpoint explicitly documents placeholder support; otherwise wait for the real song_id.

Text field limits

Exceeding a text limit returns HTTP 400 directly: nothing is generated, nothing is pre-charged and no task record is created. Counting is by Unicode character (one Chinese character counts as 1) and leading/trailing spaces count too.

The message names the offending field and reports the measured length, so those two numbers are all you need to trim it:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Applies to: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

One exception: the description field of POST /api/music/sounds is capped at 100 characters, because the sound-effect path uses the platform's shorter limit.

Asynchronous generation and audio addresses

Music generation endpoints work asynchronously by default. When the first response carries status of pending, submitted or processing, an empty audio_url, video_url or cover_url is normal and does not mean the task failed. Save the real song_id (or the client_request_id the endpoint returned) and poll the matching query endpoint; only read and download an audio address once the status is complete.

⚠️ Audio addresses expire after 7 days — transfer your files in time

audio_url, wav_url, video_url and the addresses returned by the download endpoints are served from the platform's object storage and expire after 7 days by default (the files are recycled; an old address returns 404 / fails to download).

• Within those 7 days, move the files into your own storage (your own object storage, a CDN or a server disk). Do not treat our addresses as long-lived links.
• An expired address does not require regenerating the song and costs nothing extra: call the song query API (or the media download API) again to get a fresh valid address for that song.

Wait times and timeout settings

Generation endpoints are synchronous: the order is only accepted and handed to the platform for generation when the response arrives. Before that, the service has to schedule an account and pass the required safety check, and there is no intermediate response — no other endpoint can see the order either. So the only reliable evidence that "something was generated" is the response itself, not anything you observe while waiting.

Measured wait times (production /api/music/create family, 2026-09-18 to 2026-09-20)

• About 10% of requests take longer than 30 seconds and about 1% take 1–2 minutes. A slow request usually means this one had to pass a safety check first.
• Request fields, response shape, error codes and billing are unchanged, so existing integrations only need to raise their client timeout — no other code change.

Integration requirements

1. Set the client timeout to 300 seconds or more. Clients that default to 30, 60 or 120 seconds will disconnect while waiting.
2. No response does not mean nothing was generated. On a timeout or dropped connection the order may already be accepted and generating.
3. Do not retry immediately after a timeout: a duplicate submission creates a second order and charges again.
4. If the connection dropped, list your songs with GET /api/music/songs (newest first) a little later — accepted orders appear normally. Only resubmit once you have confirmed the order is really absent.
5. When reporting a problem, include the X-Oneapi-Request-Id response header so the single request can be located directly.

Prefer not to hold a long connection? Use accept-receipt mode. POST /api/music/create and POST /api/music/create/custom support an optional accept receipt: add "accept_mode": "async" to the body (or the header X-Accept-Mode: async) and the endpoint returns 202 immediately with a receipt number while generation continues in the background; poll GET /api/music/requests/{request_id} for progress. A client with only a few tens of seconds of timeout then cannot misread "no response" as "nothing generated", and cannot double-charge through retries. See "Accept-receipt mode" in the Simple mode generation API.

For reference: python requests uses timeout=300, urllib uses urlopen(..., timeout=300), Node uses req.setTimeout(300000), curl uses --max-time 300.

Recommended endpoint list

/api/voice/clone/* and /api/music/generate-with-voice are the early voice-clone chain and are not recommended for new integrations; use the 【Recommended】 Voice profile API instead.

Advanced parameters: Max Mode and Variety

Generation endpoints support these two optional parameters (omitting them keeps the previous behaviour and price):

These parameters are supported by: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• The 2× price in practice: an endpoint that costs ¥0.6 per call becomes ¥1.2 with max_mode; generate with a chosen voice costs ¥1.2 per call and ¥2.4 with Max Mode; the voice cover of the 【Recommended】 Voice profile API is also ¥1.2 per call (¥2.4 with max_mode).
• variety only applies to the suno-v6 family (suno-v6, suno-v6-wild, suno-v6-mini); sending it with any other model returns 400.
• Sound effects, stems, concat, WAV and the Studio edit actions (crop, remove section, fade, reverse, speed and so on) do not accept these parameters — sending them explicitly returns 400, so that a parameter is never silently ignored.
• variety is the raw integer 0-4; style_weight and weirdness_constraint are decimals from 0 to 1, so the scales differ.

Common song response fields

Generation, cover, extend, separation and query endpoints usually return an array of songs with these fields:

Four steps to integrate (minimal working example)

Work through these four steps and you have your first song; each step's full field list is on the matching page in the recommended endpoint list.

# 1) Submit a generation: ¥0.6, returns 2 songs
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Mandarin pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Poll the task until status is completed (every 3-5 seconds is a good interval)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "the song_id returned in step 1"}'

# 3) Get a media address: read endpoints are free; song / wav / video / cover / midi are available
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "the same song_id", "kind": "song"}'

When something goes wrong: 401 / 402 / 403 / 429 are covered in the error reference; timeouts and duplicate charges in "Wait times and timeout settings" above; per-endpoint detail in the recommended endpoint list below.

Recommendations

• New integrations should use suno-v6 throughout.
• For endpoints that quote a default price, the amount actually charged follows the current back-office price configuration and the requested model.
• Generation endpoints normally return a task first; read the final audio through /api/music/query.
• wait_completion=true blocks until finished and suits low-volume testing; in production, polling is preferred.
• Generation endpoints can take a long time to return — set the client timeout to 300 seconds or more, and remember that "no response" is not the same as "nothing generated"; see "Wait times and timeout settings" above.
• Upload, cover, replace and WAV capabilities depend on platform accounts and source-clip permissions; when they fail, read the returned message or error_message first.

About this documentation

This page was reorganised around the capabilities the Create UI actually exposes, and new integrations should read it first. The older API documentation is still available in the "Legacy API documentation (compatible)" section for callers who want to keep using it.