Skip to main content
POST
custom determines which fields take effect: fields written under the wrong mode are silently ignored by the upstream (no error). With custom=true (custom), prompt (lyrics), title, style, negative_tags, auto_lyrics, persona_id, style_weight, weirdness_constraint, and audio_weight take effect; with custom=false (inspiration), prompt is used as the inspiration description, and title/style and the custom fields above are ignored. vocal_gender works in both modes.
This endpoint uses a separate route, so some field names differ from other endpoints: style (not tags).

Authorizations

Authorization
string
required
All endpoints require authentication using a Bearer TokenGet an API Key:Visit the API Key management page to get your API KeyAdd the following to the request headers when using it:

Body

model
string
default:"suno"
Audio model. Currently pass suno (defaults to suno if omitted).
custom
boolean
default:"false"
false=inspiration mode; true=custom mode (prompt used as lyrics). Defaults to false.
instrumental
boolean
default:"false"
true=instrumental only, no vocals. Defaults to false.
version
string
required
Generation version: v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5, affects audio quality and billing. Required in both modes; omitting it returns 400 directly.
prompt
string
Inspiration prompt / lyrics. Required when custom=false (used as the inspiration description). When custom=true: required if instrumental=false (used as lyrics); optional if instrumental=true. If missing, a 400 is returned at submission time (no upstream call, no charge).
title
string
Title (custom mode). Ignored when custom=false (inspiration mode).
style
string
Style tags (custom mode, maps to upstream tags). Ignored when custom=false (inspiration mode).
negative_tags
string
Negative style tags (styles you don’t want). Only takes effect when custom=true.
auto_lyrics
boolean
true=rewrite the provided lyrics creatively. Only takes effect when custom=true.
persona_id
string
Persona style id. Only takes effect when custom=true.
vocal_gender
string
Vocal gender: Male / Female (m / f / male / female are also accepted and normalized by the backend). Works in both modes.
style_weight
number
Style weight, 0.001.00. Only takes effect when custom=true.
weirdness_constraint
number
Creativity, 0.001.00. Only takes effect when custom=true.
audio_weight
number
Audio weight, 0.001.00. Only takes effect when custom=true.
Getting the result: This endpoint is an async task. After submitting you get a task_id; poll GET /v1/music/tasks/{task_id} at 3–5s intervals until status is completed or failed (music generation typically takes 30–120s; while generating, status is pending and progress goes queued 10 → ready 50 → done 100). On completion take audio_url from data.result.music[] (also image_url / video_url / title / duration, etc.). On failure data.error.message gives the reason and the pre-deducted quota is automatically refunded.

Response

code
integer
Response status code
data
array
Returned data array