灵感生成
- 用 1 到 4 段公网音频直链作为参考，生成新歌
- 与翻唱不同：这里给的是音频参考，不是源曲引用
- 直接用 URL，不需要 task_id
认证
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请求参数
音频模型，默认 suno，当前只有这一个取值。
可公开访问的音频 URL 数组，1 到 4 个元素。
直接给音频直链，不是 task_id。模型会参考这些音频的风格与结构生成新曲。
公共版本，取值 v6（默认）、v6-wild、v6-mini。与 custom_model_id 互斥。
创建模型任务返回的完整 UUID。使用时省略 version 字段。
歌词或内容。
标题。
风格标签。
排除的风格标签。
风格权重，取值 0.00 到 1.00。
创意度权重，取值 0.00 到 1.00。兼容旧名 weirdness_constraint，新请求请用 weirdness。
音频权重，取值 0.00 到 1.00。
人声性别，取值 Male 或 Female。
为 true 时对输入歌词进行二次创作。
风格变化程度，取值 off、normal、high、extra、max。可省略。
启用 Max 模式，默认 false，按普通售价的 2 倍计费。
输出音频格式，取值 mp3、m4a、wav。
The audio model; defaults to suno, currently the only value.
An array of publicly accessible audio URLs, 1 to 4 elements.
Pass audio direct links, not task_ids. The model draws on these clips' style and structure to generate a new song.
The public version: v6 (default), v6-wild, or v6-mini. Mutually exclusive with custom_model_id.
The full UUID returned by a model creation task. Omit the version field when using it.
Lyrics or content.
The title.
Style tags.
Style tags to exclude.
Style weight, 0.00 to 1.00.
Creativity weight, 0.00 to 1.00. The old name weirdness_constraint is supported, but new requests should use weirdness.
Audio weight, 0.00 to 1.00.
Vocal gender: Male or Female.
When true, rewrites the supplied lyrics once more.
Degree of style variation: off, normal, high, extra, max. May be omitted.
Enables Max mode; defaults to false; billed at 2× the regular price.
Output audio format: mp3, m4a, or wav.
这个端点不接受的字段
| 字段 | 说明 |
|---|---|
custom | 本端点没有灵感/自定义模式的区分 |
instrumental | 不支持纯音乐标记 |
gpt_description | 用 prompt 而非这个字段 |
persona_id | 不支持绑定 Persona |
| 目标时长字段 | 不支持指定 duration 或 duration_s |
传了这些字段不会报错，但也不会生效。
| Field | Notes |
|---|---|
custom | This endpoint has no inspiration/custom mode distinction |
instrumental | Instrumental flag isn't supported |
gpt_description | Use prompt instead of this field |
persona_id | Binding a Persona isn't supported |
| Target duration fields | Specifying duration or duration_s isn't supported |
Passing these doesn't error, but they have no effect.
提交响应
响应状态码，成功为 200。
任务状态，提交成功时固定为 submitted。
任务唯一标识，用于轮询 GET /v1/music/tasks/{task_id}。
The response status code; 200 on success.
The task status; fixed at submitted on successful submission.
The unique task identifier, used to poll GET /v1/music/tasks/{task_id}.
轮询结果
取值 pending、processing、completed、failed。生成中为前两者。
进度百分比，0 到 100，节点不保证固定变化。
任务完成后的成品音频地址。
失败原因。失败自动退回预扣额度。
轮询间隔建议 3 到 5 秒，直到 status 变为 completed 或 failed。典型耗时 30 到 120 秒。
pending, processing, completed, or failed. The first two mean still generating.
Progress percentage, 0 to 100; node changes aren't guaranteed to be in fixed steps.
The finished audio URL once the task completes.
The failure reason. On failure the held balance is refunded automatically.
Poll every 3 to 5 seconds until status becomes completed or failed. Typical duration is 30 to 120 seconds.
参考音频怎么准备
audio_urls 用的链接必须是公网可访问的直链。几个实际要求：
- 不能是需要登录才能下载的地址
- 不能是网页地址（比如 YouTube 链接），必须是音频文件本身
- 音频格式建议用 mp3 或 wav
- 单条音频不宜过长，截取代表性片段即可
四段参考音频不要风格冲突太大。模型会试图融合所有参考，一段重金属加一段摇篮曲，结果往往两边都不像。想要某种风格占主导，把它放在数组第一位，并调高 style_weight。
The links in audio_urls must be publicly accessible direct links. Some practical requirements:
- Not an address that requires login to download
- Not a web page URL (such as a YouTube link); it must be the audio file itself
- mp3 or wav recommended
- Individual clips shouldn't be too long; a representative excerpt is enough
Don't make the four references too stylistically conflicting. The model tries to blend all references, and one heavy-metal track plus one lullaby tends to resemble neither. To make one style dominate, put it first in the array and raise style_weight.
错误码
For error response formats, 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.