Skip to main content
POST
Referencing the source track: The source must be your own audio uploaded via uploadTask; pass that upload task’s task_id + audio_index (which track in the result music[], 1-based, defaults to 1). Using a generated track as the source will fail—you can only reference tracks you uploaded yourself.
custom determines which fields take effect: fields written under the wrong mode are silently ignored by the upstream (no error). With custom=true, prompt (lyrics), title, tags, negative_tags, style_weight, weirdness_constraint, and audio_weight take effect and gpt_description is ignored; with custom=false, only gpt_description is read (required in that case — if missing, a 400 is returned at submission time). vocal_gender works in both modes. If custom is omitted, the backend infers it in this order: prompt present → true; no prompt but gpt_description present → false; otherwise tags/title present → true.

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).
task_id
string
required
The task_id of the uploadTask upload that holds the source track (must be a track you uploaded yourself; using a track from a generation task as the source will fail). If missing or the source cannot be resolved, a 400 is returned at submission time.
audio_index
integer
default:"1"
Which track in the source job’s result data.music[] (1-based; defaults to 1; a single generation usually produces 2 tracks: indexes 1 and 2).
version
string
default:"v5.5"
Generation version: only v5 / v5.5; defaults to v5.5 if omitted. Any other value returns 400 directly at submission time.
custom
boolean
true=custom mode (prompt used as lyrics); false=inspiration mode (uses gpt_description); if omitted, inferred from the content (see the Warning above).
prompt
string
Lyrics. Takes effect when custom=true (ignored in inspiration mode).
gpt_description
string
Inspiration prompt. Required when custom=false — if missing, the request fails with 400 at submission (the upstream is not called, nothing is charged).
title
string
Title. Only takes effect when custom=true.
tags
string
Style tags. Only takes effect when custom=true.
negative_tags
string
Style tags to exclude. Only takes effect when custom=true.
style_weight
number
Style weight, 0.001.00 (out-of-range values return 400 directly at submission time). Only takes effect when custom=true.
weirdness_constraint
number
Creativity weight, 0.001.00 (alias weirdness). Only takes effect when custom=true.
audio_weight
number
Audio weight, 0.001.00. Only takes effect when custom=true.
vocal_gender
string
Vocal gender: Male / Female. Works in both modes.
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[]. 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