Custom mode generation API

Updated 2026-09-18 · Suno-API team

Endpoint description

Custom mode suits the case where you already have lyrics, style and title ready and want control over the singing voice, the style influence strength and the generation randomness.

Endpoint: POST /api/music/create/custom

Billing: Paid, currently 0.6 ¥ per call by default. Each call usually returns 2 songs; the amount actually charged follows the current back-office price configuration.

Max Mode / Variety: this endpoint supports the optional parameters max_mode and variety (0-4). With max_mode on, this call is billed at 2× the price (0.6 → 1.2 ¥ per call); variety costs nothing extra. What they mean and how to send them is in the "Advanced parameters" section of the New API overview.

Wait times and timeouts (important): this is a synchronous endpoint — the order is only accepted and handed to generation when the response arrives. Measured, most requests return in 1-3 seconds, about 10% take longer than 30 seconds, and the longest is about 230 seconds. Set your client timeout to 300 seconds or more; no response does not mean nothing was generated, and do not retry immediately after a timeout (that duplicates the order and charges again). If the connection dropped, confirm later with GET /api/music/songs. See "Wait times and timeout settings" in the New API overview.

Request parameters

Headers

Body parameters

Advanced parameter notes

Vocal gender vocal_gender

• Send m or male for a male voice, f or female for a female voice.
• The service normalises male and female into m and f respectively.
• With instrumental=true, no vocal gender parameter is sent to the generation service.

Style influence style_weight

Controls how strongly the result follows style_tags. The higher the value, the more the result tends to follow the style tags you supplied.

Randomness weirdness_constraint

Controls how varied and experimental the result tends to be. Higher values usually give more variation; lower values usually give a safer result.

Both numeric parameters range from 0.0 to 1.0, and 0 is a valid explicit value. Only omitting the field entirely means "not specified".

When filling them in, note that these are decimal fractions, not percentage integers. Suggested reference: 0.0 to 0.3 is conservative, 0.4 to 0.6 is balanced, 0.7 to 1.0 is more experimental; if you have no strong preference use 0.5, or simply omit them. Example: weirdness_constraint: 0.5, never 50 or 50%.

With instrumental=true the result is instrumental, so the lyrics and vocal gender do not take effect the way they do for a sung song; if you need vocals, send false or omit the field. Boolean fields must use JSON true/false, not strings.

Python request example

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nNight falls on the sea\nAn evening breeze drifts past the window',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Evening breeze by the sea',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Accept-receipt mode (optional)

This endpoint also supports the accept-receipt mode from the Simple mode generation API: with "accept_mode": "async" in the body (or the header X-Accept-Mode: async), the endpoint immediately returns 202 and a receipt number, generation continues in the background, and you track progress with GET /api/music/requests/{request_id}.

It suits clients that should not hold long connections, or that do not want a timeout to be mistaken for "nothing generated". Without that parameter, behaviour is exactly as before.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Evening breeze by the sea",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

The response shape and polling method are in the "Accept-receipt mode" section of the Simple mode generation API.

Parameter validation

These cases return HTTP 400, and the error's message names the invalid field:

• style_weight or weirdness_constraint is not a number.
• A numeric value is below 0.0 or above 1.0.
• vocal_gender is not one of m, f, male, female.

Text field limits

These fields also return HTTP 400 when too long, and never enter generation or pre-charge. Counting is by Unicode character (one Han character counts as 1) and leading/trailing spaces count too:

The error message looks like style_tags must not exceed 1000 characters; received 2772: the first word is the offending field name and the end is the measured count, so on a 400 you can trim by those two numbers instead of trying field after field. The general conventions are in "Text field limits" in the New API overview.

Response

The endpoint usually returns an array containing 2 songs. An asynchronous request usually starts in pending; save the song_id and read the final status and audio address through the song query API. Song fields are the same as in the Simple mode generation API.

Compatible fields

New integrations should use snake_case throughout. If a single request carries both snake_case and camelCase, the snake_case value wins.