Skip to main content
POST

​
概览

POST /api/v1/music/{action} 是 Suno 音乐的主入口，路径中的 action 为 33 个动作之一。每个动作都会创建一个 suno 模型的异步任务：保存 data.task_id，再通过 POST /api/v1/task/status 查询直到任务结束。每次调用计费一次，各动作积分见 Suno 计费。 POST /api/v1/task/submit/suno 仍然可用，等同于 generate 动作。
响应沿用常规的提交格式，并额外返回 action：

​
通用规则

  • 严格字段。 每个动作只接受下文为它列出的字段。传入该动作不接受的音乐字段会返回 HTTP 422 validation_failed，例如 music action bpm does not accept version。不需要的字段请直接省略。
  • 未知动作返回 HTTP 404 music_action_not_found。
  • 文本长度按 Unicode 字符计算。音频 URL 必须是公网可访问的 HTTP(S) 地址，最多 2,048 个字符。
  • 之前的任务只能通过 Wizzx task_id 引用，见下方「引用已有任务」。
  • 音乐动作与提交接口共用限流。参数校验和来源任务校验失败时，不会预扣任何积分。

​
通用字段

以下字段在所有接受它们的动作中含义相同。 下文动作表格使用以下简称：
  • 模型选择：version 或 custom_model_task_id
  • 风格字段：title、style、negative_tags
  • 权重：style_weight、weirdness、audio_weight
  • 模式字段：custom、prompt、gpt_description

​
自定义模式与灵感模式

部分动作可以在自定义模式（自己写歌词和风格）与灵感模式（由 Suno 根据描述创作）之间切换。 灵感模式下，generate 拒绝 title、style、negative_tags、auto_lyrics、persona_task_id、duration 与 max_mode；其他动作拒绝 prompt、title、style、negative_tags、auto_lyrics、persona_task_id、duration、max_mode、style_weight 与 audio_weight。自定义模式下拒绝 gpt_description。

​
引用已有任务

许多动作基于你已经生成的曲目：
  • task_id + audio_index 选择一首曲目。audio_index 是该曲目在来源任务 result.tracks 中从 1 开始的 index，默认 1。
  • mashup 改用 task_ids（正好两个任务）与 audio_indexes（两个元素，默认 [1, 1]）。
  • custom_model_task_id 必须指向已完成的 create-model 任务，persona_task_id 必须指向已完成的 persona 或 create-voice 任务。
被引用的任务必须是你自己的、状态为 SUCCEEDED 的 suno 任务。只有产出曲目的动作才能作为曲目来源：generate、inspo、sounds、upload、upload-cover、upload-extend、extend、cover、remaster、stems、stems-all、add-vocals、add-instrumental、add-stem、replace-section、remove-section、crop、fade-in、fade-out、adjust-speed、concat、mashup 与 sample。歌词、风格、分析、Persona、模型、声音、视频与下载结果不能作为来源。 部分动作要求特定类型的来源： 扣费前，网关还会检查 audio_index 在来源任务中存在，且 continue_at、end_s、fade_duration 不超出来源曲目时长。任一检查失败都会返回 HTTP 422，不会预扣积分。
2026 年 10 月 15 日之前完成的任务没有 result 对象。它们仍可作为来源，但无法提前校验曲目序号与时间；超出范围的值会导致任务失败，积分会退回。

​
动作

所有动作的输出都在任务状态的 result 对象中返回。

​
创作

​
基于已有曲目

除特别说明外，以下动作都接受 task_id（必填）与 audio_index（可选）。

​
编辑

所有编辑动作都接受 task_id（必填）与 audio_index（可选），来源可以是任意曲目。 时间范围以秒为单位，须满足 0 ≤ start_s < end_s ≤ 曲目时长。

​
分析与导出

以下动作接受 task_id（必填）与 audio_index（可选），来源可以是任意曲目。

​
完整示例

每一步都是单独计费的任务。被引用的任务必须先变为 SUCCEEDED。

​
生成、续写并拼接为完整歌曲

第 1 步。 用 POST /api/v1/music/generate 生成：
查询任务，从 result.tracks 中选一首，例如 "index": 2 的曲目。 第 2 步。 用 POST /api/v1/music/extend 从 1:30 处续写该曲目：
第 3 步。 用 POST /api/v1/music/concat 并传入 extend 任务的 task_id，拼接为完整歌曲：

​
给自己的音频加人声

第 1 步。 用 POST /api/v1/music/upload 上传音频：
第 2 步。 用 POST /api/v1/music/add-vocals 并传入 upload 任务的 task_id：

​
分轨与下载文件

用 POST /api/v1/music/stems 从已完成的歌曲中提取一个分轨：
改用 stems-all 可把曲目拆成全部分轨。需要曲目的 WAV 与 MP3 文件时，调用 POST /api/v1/music/download：
任务完成后，文件按请求顺序列在 result.files 中。

​
错误

错误格式与重试建议见 错误码。

授权

​
Authorization
string
header
必填

Wizzx API key. This is not a JWT.

路径参数

​
action
enum<string>
必填

Music action. Unknown actions return 404 music_action_not_found.

可用选项:
generate,
inspo,
sounds,
lyrics,
upsample-tags,
upload,
upload-cover,
upload-extend,
create-model,
create-voice,
extend,
concat,
cover,
remaster,
add-vocals,
add-instrumental,
add-stem,
mashup,
sample,
persona,
replace-section,
remove-section,
crop,
fade-in,
fade-out,
adjust-speed,
stems,
stems-all,
midi,
aligned-lyrics,
bpm,
music-video,
download

请求体

application/json

Request body for POST /api/v1/music/{action}. Each action accepts only its own fields, listed per action in x-wizzx-music-actions; sending a field the action does not accept returns 422. Earlier tasks are referenced by Wizzx task_id only and must be your own SUCCEEDED suno tasks.

​
prompt
string

Lyrics in custom mode (at most 5000 characters). A description (at most 3000 characters) for generate inspiration mode, the lyrics topic, and the sounds description.

Maximum string length: 5000
​
gpt_description
string

Song description for inspiration mode (custom=false) on actions other than generate.

Maximum string length: 3000
​
custom
boolean

Custom (lyrics) mode. generate defaults to false; extend defaults to true; upload-cover requires it; cover, add-vocals, add-instrumental, add-stem, mashup, and sample infer it when omitted (prompt, style, or title means true; gpt_description means false).

​
instrumental
boolean
默认值:false

No vocals. Cannot be combined with vocal_gender.

​
version
enum<string>
默认值:v6

Case-insensitive. All versions cost the same. Cannot be combined with custom_model_task_id.

可用选项:
v6,
v6-wild,
v6-mini
​
custom_model_task_id
string<uuid>

task_id of your SUCCEEDED create-model task. Replaces version; cannot be combined with version or persona_task_id.

​
persona_task_id
string<uuid>

task_id of your SUCCEEDED persona or create-voice task. Custom mode only.

​
title
string

Custom mode only on actions with a mode switch.

Maximum string length: 80
​
style
string

Style tags. Custom mode only on actions with a mode switch. Required by upsample-tags.

Maximum string length: 1000
​
negative_tags
string

Styles to avoid. Custom mode only on actions with a mode switch.

Maximum string length: 1000
​
style_weight
number

How strongly to follow style, 0-1. Custom mode only on actions other than generate.

必填范围: 0 <= x <= 1
​
weirdness
number

How experimental the result is, 0-1.

必填范围: 0 <= x <= 1
​
audio_weight
number

How closely to follow the source audio, 0-1. Custom mode only on actions other than generate.

必填范围: 0 <= x <= 1
​
vocal_gender
enum<string>

Case-insensitive; m and f are accepted. Cannot be combined with instrumental=true.

可用选项:
Male,
Female
​
auto_lyrics
boolean
默认值:false

Custom mode only.

​
variety
enum<string>
可用选项:
off,
normal,
high,
extra,
max
​
max_mode
boolean
默认值:false

Higher quality at double the price. Requires custom mode on actions with a mode switch.

​
audio_format
enum<string>
可用选项:
mp3,
m4a,
wav
​
duration
integer

Target length in seconds; actual length may differ. Custom mode only on actions with a mode switch. Does not change the price.

必填范围: 10 <= x <= 360
​
task_id
string<uuid>

Source task: one of your SUCCEEDED suno tasks that produced tracks.

​
audio_index
integer
默认值:1

1-based result.tracks[].index of the source task.

必填范围: 1 <= x <= 20
​
task_ids
string<uuid>[]

mashup: exactly two source tasks.

Required array length: 2 elements
​
audio_indexes
integer[]

mashup: track index for each task_ids entry.

Required array length: 2 elements
必填范围: 1 <= x <= 20
​
audio_url
string<uri>

Publicly reachable HTTP(S) audio URL, at most 2048 characters.

Maximum string length: 2048
Pattern: ^https?://
​
audio_urls
string<uri>[]

inspo: 1-4 reference audio URLs. create-model: 6-24 training audio URLs.

Required array length: 1 - 24 elements

Publicly reachable HTTP(S) audio URL, at most 2048 characters.

Maximum string length: 2048
Pattern: ^https?://
​
continue_at
number

Seconds into the source audio where the continuation starts. For extend it must be less than the source track duration.

必填范围: x >= 1
​
start_s
number

Section start in seconds.

必填范围: x >= 0
​
end_s
number

Section end in seconds. Greater than start_s and not beyond the source track duration.

必填范围: x > 0
​
fade_duration
number

Fade length in seconds; not longer than the source track.

必填范围: x > 0
​
speed
number
必填范围: 0.25 <= x <= 4
​
keep_pitch
boolean
默认值:true
​
stem_type
enum<string>
默认值:lead_vocal

Case-insensitive.

可用选项:
lead_vocal,
drum_kit,
bass,
backing_vocals,
piano,
electric_guitar,
percussion,
string_section,
synth,
acoustic_guitar,
sound_effects,
synth_pad,
synth_bass,
guitar,
brass_section,
organ,
electronic_drum_kit,
lead_electric_guitar,
synth_keys,
rhythm_electric_guitar,
electric_piano,
upright_bass,
keyboards,
distorted_electric_guitar,
kick,
snare,
risers,
synth_strings,
synth_lead,
woodwinds,
flute,
harp,
tambourine,
trumpet,
arpeggiator,
accordion,
fiddle,
pedal_steel_guitar,
synth_voice,
violin,
digital_piano,
synth_brass,
mandolin,
choir,
banjo,
bells,
clarinet,
tenor_saxophone,
trombone,
shaker,
french_horn,
glockenspiel,
electric_bass,
cello,
timpani,
harmonica,
marimba,
vibraphone,
lap_steel_guitar,
saxophone,
orchestra,
horns,
cymbals,
hand_clap,
oboe,
celesta,
congas,
drone,
alto_saxophone,
double_bass,
ukulele,
harpsichord,
baritone_saxophone,
xylophone,
tuba,
bass_guitar,
whistle,
lead_guitar,
rhodes,
808,
bongos,
bassoon,
cowbell,
viola,
sitar,
steel_drums,
piccolo,
theremin,
bagpipes,
hi_hat,
music_box,
melodica,
tabla,
koto,
djembe,
taiko,
didgeridoo
​
infill_lyrics
string

replace-section: lyrics for the replaced section.

Maximum string length: 5000
​
variation_category
enum<string>
可用选项:
subtle,
normal,
high
​
sound_type
enum<string>
可用选项:
one-shot,
loop
​
bpm
integer
必填范围: 1 <= x <= 300
​
key
enum<string>

Sharp notation; append m for minor.

可用选项:
C,
Cm,
C#,
C#m,
D,
Dm,
D#,
D#m,
E,
Em,
F,
Fm,
F#,
F#m,
G,
Gm,
G#,
G#m,
A,
Am,
A#,
A#m,
B,
Bm
​
lyrics_model
enum<string>
可用选项:
classic,
remi
​
name
string

create-model or persona name.

Maximum string length: 80
​
description
string

persona description.

Maximum string length: 1000
​
formats
enum<string>[]

Duplicates are ignored.

Minimum array length: 1
可用选项:
mp3,
m4a,
wav

响应

Task accepted

​
code
enum<integer>
必填
可用选项:
0
​
message
string
必填
示例:

"success"

​
data
object
必填
​
request_id
string<uuid>
必填