生成音乐
- Suno 的主生成接口，异步任务
- 两种模式：灵感模式（给描述）与自定义模式（给歌词）
- 通常 30 到 120 秒出结果
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY两种模式
| 模式 | custom | prompt 的含义 | 生效的字段 |
|---|---|---|---|
| 灵感模式 | false（默认） | 创意描述，不超过 3000 字符 | 只有 prompt 与版本 |
| 自定义模式 | true | 歌词正文，不超过 5000 字符 | title、style、negative_tags、auto_lyrics、persona_id 等 |
灵感模式下，title、style、negative_tags、auto_lyrics、persona_id 全部被忽略。
两种模式都生效。
两种模式都生效。
两种模式都生效。
两种模式都生效。
| Mode | custom | Meaning of prompt | Fields that apply |
|---|---|---|---|
| Inspiration | false (default) | Creative description, up to 3000 characters | Only prompt and the version |
| Custom | true | Lyrics body, up to 5000 characters | title, style, negative_tags, auto_lyrics, persona_id, and more |
In inspiration mode, title, style, negative_tags, auto_lyrics, and persona_id are all ignored.
Applies in both modes.
Applies in both modes.
Applies in both modes.
Applies in both modes.
请求参数
音频模型，目前只传 suno，不传也按 suno 处理。
默认 false。false 时按灵感模式理解 prompt 为创意描述；true 时按自定义模式把 prompt 当歌词。
默认 false。为 true 时输出纯音乐，不含人声。
公共版本号，取值 v6、v6-wild、v6-mini。
与 custom_model_id 至少提供一个，若改用自定义模型则不要填本字段。
填创建自定义模型任务时返回的完整 UUID。与 version、persona_id 三者互斥，填了按自定义模型价格档计费。
灵感模式下是描述性提示词，必填且上限 3000 字符。
自定义模式且非纯音乐时必填，上限 5000 字符。自定义纯音乐可以不填。
歌曲标题，上限 80 字符。只在自定义模式有用，灵感模式下会被丢弃。
风格标签，上限 1000 字符。只在自定义模式有用。
注意本端点叫 style，其他操作端点叫 tags。
列出不想出现的风格。自定义模式才校验。
为 true 会对你给的歌词再做一次加工改写。自定义模式才生效。
绑定某个 Persona 风格。自定义模式才生效，且不能与 custom_model_id 同用。
人声性别。取值 Male、Female，简写 m、f、male、female 由后端归一化。
风格权重，取值 0.00 到 1.00。两种模式都校验并生效。
创意/怪异度，取值 0.00 到 1.00。两种模式都生效。
音频权重，取值 0.00 到 1.00。两种模式都生效。
风格变化幅度，取值 off、normal、high、extra、max。可不传，官方未给固定默认值。
开启 Max 模式，默认 false。前提是 custom: true，按常规价格两倍收费。
输出音频格式，取值 mp3、m4a、wav。不填由服务端自行决定。
期望时长，取值 10 到 360 秒。仅自定义模式可用，最终时长以任务实际结果为准。
The audio model; currently only suno, and omitting it is treated as suno.
Defaults to false. With false, prompt is read as a creative description (inspiration mode); with true, prompt is treated as lyrics (custom mode).
Defaults to false. When true, outputs instrumental music with no vocals.
The public version: v6, v6-wild, or v6-mini.
Provide at least one of this and custom_model_id; if you switch to a custom model, leave this field out.
The full UUID returned by a custom model creation task. Mutually exclusive with version and persona_id; providing it bills at the custom model price tier.
In inspiration mode it's the descriptive prompt, required, up to 3000 characters.
In custom mode it's required unless instrumental, up to 5000 characters. Custom instrumental can omit it.
The song title, up to 80 characters. Only useful in custom mode; discarded in inspiration mode.
Style tags, up to 1000 characters. Only useful in custom mode.
Note this endpoint calls it style while other operation endpoints call it tags.
Styles you don't want. Validated only in custom mode.
When true, the lyrics you supply get another round of rewriting. Takes effect only in custom mode.
Binds a Persona style. Takes effect only in custom mode, and can't be used together with custom_model_id.
Vocal gender: Male or Female; the shorthand m, f, male, female is normalized server-side.
Style weight, 0.00 to 1.00. Validated and applied in both modes.
Creativity/weirdness, 0.00 to 1.00. Applies in both modes.
Audio weight, 0.00 to 1.00. Applies in both modes.
Degree of style variation: off, normal, high, extra, max. May be omitted; the official docs give no fixed default.
Enables Max mode; defaults to false. Requires custom: true; billed at twice the regular price.
Output audio format: mp3, m4a, or wav. Left to the server when omitted.
Desired duration, 10 to 360 seconds. Available only in custom mode; the final length follows the task's actual result.
响应
状态码，200 表示已受理。
提交后为 submitted。
任务 ID，用于轮询。
The status code; 200 means accepted.
submitted after submission.
The task ID, for polling.
取结果
用 GET /v1/music/tasks/{task_id} 轮询。任务查询的字段说明见「Suno 通用约定与任务查询」。
完成后结果在 data.result.music[]，每一项含：
| 字段 | 说明 |
|---|---|
audio_url | 音频地址 |
image_url | 封面图 |
video_url | 视频地址（部分任务返回） |
title | 曲目标题 |
duration | 实际时长 |
失败时 data.error.message 给出原因，预扣额度会自动退回。
Poll with GET /v1/music/tasks/{task_id}. For task query fields see "Suno conventions and task polling".
On completion the results are in data.result.music[], each with:
| Field | Description |
|---|---|
audio_url | The audio URL |
image_url | The cover image |
video_url | The video URL (returned by some tasks) |
title | The track title |
duration | The actual duration |
On failure, data.error.message gives the reason, and the held balance is refunded automatically.
几个容易踩的点
灵感模式下 title 和 style 会被丢掉。 想要指定标题与风格标签，必须 custom: true。
Max 模式需要两个条件。 max_mode: true 之外还要 custom: true，否则不生效。
version 和 custom_model_id 不能同时给。 同时发送会报错。
歌词用段落标记。 以 [Verse]、[Chorus] 这类标记开头，换行在 JSON 里写成 \n。
In inspiration mode, title and style are dropped. To specify a title and style tags, you must set custom: true.
Max mode needs two conditions. Besides max_mode: true you also need custom: true, or it won't take effect.
version and custom_model_id can't both be given. Sending both errors out.
Use section tags in lyrics. Start with markers like [Verse] and [Chorus], and write newlines as \n inside JSON.
错误码
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效 |
| 401 | authentication_error | 身份验证失败，请检查您的API密钥 |
| 402 | payment_required | 账户余额不足，请充值后再试 |
| 429 | rate_limit_error | 请求过于频繁，请稍后再试 |
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid request parameters |
| 401 | authentication_error | Authentication failed; check your API key |
| 402 | payment_required | Insufficient account balance; top up and retry |
| 429 | rate_limit_error | Too many requests; try again later |
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
使用示例
提交一个任务并拿到 task_id：
提交成功只表示任务已受理。真正的产物要拿返回的 task_id 去任务查询接口轮询，status 变成 completed 之后才有结果。
Submit a task and get a task_id:
A successful submission only means the task was accepted. To get the actual output, poll the task query endpoint with the returned task_id; results appear only after status becomes completed.