通用约定与任务查询
- Suno 系列的公共约定：认证、版本、异步流程、任务查询与结果结构
- 所有生成、编辑、工具接口都是异步任务
- 统一从提交响应的
data[0].task_id取任务号
认证
所有接口均使用 Bearer Token 进行认证。
所有 Suno 接口共用。
获取 API Key：访问控制台 创建。
请求时在请求头中添加：
Authorization: Bearer YOUR_OAIRoute_KEYAll endpoints authenticate with a Bearer token.
Shared by every Suno endpoint.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY查询参数
提交任务时返回的任务 ID。
失败信息的返回语言，例如 zh。只影响错误文案的本地化，不改变歌曲或歌词的语言。
当前没有取消已提交 Suno 任务的端点。任务一旦提交就会执行完，客户端的中断只会停止本地等待。
The task ID returned when the task was submitted.
The language for failure messages, e.g. zh. Affects only the localization of error text, not the language of the song or lyrics.
There's currently no endpoint for cancelling a submitted Suno task. Once submitted, a task runs to completion; client-side aborts only stop local waiting.
版本与模型选择
公共模型有三个版本：
| 版本 | 特点 |
|---|---|
v6 | 标准 |
v6-wild | 风格更发散 |
v6-mini | 更快、更便宜 |
主生成接口必须二选一：传 version，或传创建模型任务返回的 custom_model_id。两者互斥，同时发送会报错。
编辑类操作省略 version 时回落为 v6。
custom: true 表示自定义歌词模式，custom_model_id 表示已训练的自定义模型。两者含义完全不同，前者不会自动切到自定义模型的价格档。
The public models come in three versions:
| Version | Notes |
|---|---|
v6 | Standard |
v6-wild | Wider-ranging styles |
v6-mini | Faster and cheaper |
The main generation endpoint requires one of two mutually exclusive options: pass version, or pass the custom_model_id returned by a model-creation task. Sending both errors out.
Edit operations fall back to v6 when version is omitted.
custom: true means custom-lyrics mode; custom_model_id means a trained custom model. These mean completely different things, and the former does not switch you to the custom model's price tier.
通用 V6 生成选项
这些字段只在具体端点明确列出时才发送。不支持某字段的操作应完全省略它，不要给所有操作统一塞一个默认值。
控制风格变化幅度。取值 off、normal、high、extra、max。
variety 与 Max 计费互相独立，选 variety: "max" 不会自动开启 Max 计费。
Max 模式，默认 false。支持时按普通售价 2 倍计费。
输出音频格式。取值 mp3、m4a、wav。
目标生成时长，10 到 360 秒。仅「生成」类操作支持，实际成品不保证一致。
Send these fields only where a specific endpoint documents them. An operation that doesn't support a field should omit it entirely — don't stuff a default into every operation.
Controls the degree of style variation. Values: off, normal, high, extra, max.
variety and Max billing are independent; choosing variety: "max" doesn't turn on Max billing.
Max mode; defaults to false. Where supported, billed at 2× the normal price.
Output audio format: mp3, m4a, or wav.
Target generation length, 10 to 360 seconds. Supported only by "generate" operations, and the finished track isn't guaranteed to match.
文本长度与权重限制
| 内容 | 字段（按端点区分） | 限制 |
|---|---|---|
| 灵感描述 | prompt / gpt_description | 不超过 3000 字符 |
| 歌词 | prompt（自定义模式） | 不超过 5000 字符 |
| 风格 | style / tags | 不超过 1000 字符 |
| 标题 | title | 不超过 80 字符 |
| 权重 | style_weight / weirdness / audio_weight | 0 到 1，数值 0 有效 |
字符数按 Unicode 字符计算。
权重字段名按端点不同：操作接口的新请求用 weirdness，weirdness_constraint 作兼容别名；主生成仍用 weirdness_constraint。
| Content | Field (varies by endpoint) | Limit |
|---|---|---|
| Inspiration description | prompt / gpt_description | Up to 3000 characters |
| Lyrics | prompt (custom mode) | Up to 5000 characters |
| Style | style / tags | Up to 1000 characters |
| Title | title | Up to 80 characters |
| Weights | style_weight / weirdness / audio_weight | 0 to 1; the value 0 is valid |
Character counts use Unicode characters.
Weight field names vary by endpoint: on operation endpoints' new requests use weirdness, with weirdness_constraint as a compatibility alias; main generation still uses weirdness_constraint.
引用源音轨
编辑类操作需要指向一段已生成的音频。
产出该源音轨的任务 ID。
源任务响应中 data.result.music[] 的原始位置，从 1 起，默认 1。
必须用 task_id 加 audio_index 引用，不能换成 audio_id、music_id 或 audio_url。源任务无法解析或索引越界时返回 400。
返回几首就展示几首，不要写死为 2。即使前端调整了展示顺序，后续操作仍要按原始索引引用，否则会改错曲目。
Edit operations need to point at an already-generated audio.
The task ID that produced the source track.
The original position of the track in data.result.music[] of the source task response, starting at 1; default 1.
You must reference with task_id plus audio_index; you can't substitute audio_id, music_id, or audio_url. If the source task can't be resolved or the index is out of range, it returns a 400.
Show however many tracks come back; don't hardcode 2. Even if the front end reorders the display, later operations must still reference by original index, or you'll edit the wrong track.
提交响应
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}submitted 仅代表已受理，不代表已有音频。
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}submitted only means accepted, not that audio exists yet.
查询响应字段
响应状态码。
本平台任务 ID。
任务状态。取值 pending、processing、completed、failed、unknown。
完成与否以这个字段判定，不要看 progress。
进度，通常 0 到 100。变化不保证线性。
创建时间，Unix 秒。
预计耗时，单位秒。仅供参考，不是倒计时承诺。
任务金额，美元。
消耗积分。直接使用返回值展示，不要自己换算。
完成后结果。结构随操作类型变化。
失败信息。
The response status code.
This platform's task ID.
The task status: pending, processing, completed, failed, or unknown.
Judge completion by this field, not by progress.
Progress, usually 0 to 100. Changes aren't guaranteed to be linear.
Creation time, in Unix seconds.
Estimated duration in seconds. For reference only; not a countdown promise.
Task amount in US dollars.
Credits consumed. Display the returned value directly; don't convert it yourself.
The result once complete. Structure varies by operation type.
Failure information.
result.music[] 元素字段
音频标识。
示例中为 complete。
曲目标题。
歌词文本，含段落标记。
风格标签，原始形式。
展示用风格标签。
排除风格。
风格权重。
怪异度权重。
音频权重。
实际时长，允许小数。
音频地址。
封面图。
大图封面。
The audio identifier.
complete in the examples.
The track title.
The lyrics text, with section tags.
Style tags, raw form.
Style tags for display.
Excluded styles.
Style weight.
Weirdness weight.
Audio weight.
Actual duration; decimals allowed.
The audio URL.
The cover image.
The large cover image.
结果处理要点
duration 是成品实际时长，可能与请求的目标时长不同。
权重返回 0 是合法值，不能被 JS 的 falsy 判断吞掉。
audio_url 不保证带 .mp3 后缀，按返回的实际 URL 播放或下载，不要自己加扩展名。
status 为 unknown 时保留任务 ID 并允许手动刷新，不要自动新建任务，否则会重复扣费。
duration is the finished track's actual length, which may differ from the requested target.
A returned weight of 0 is a valid value and mustn't be swallowed by JS falsy checks.
audio_url isn't guaranteed to end in .mp3 — play or download from the returned URL as-is; don't append an extension yourself.
When status is unknown, keep the task ID and allow a manual refresh. Don't create a new task automatically, or you'll be charged twice.
轮询与重试
建议首次等待约 3 秒，之后每 5 到 10 秒查一次，直到 completed 或 failed。
- 页面刷新后可用同一任务 ID 继续查询
- 网络超时不要自动重发收费的 POST
AbortController只能中断浏览器端请求与轮询，不会取消服务端任务
Wait about 3 seconds initially, then poll every 5 to 10 seconds until completed or failed.
- After a page refresh, the same task ID can resume querying
- On a network timeout, don't automatically resend the billable POST
AbortControlleronly interrupts browser-side requests and polling; it doesn't cancel the server-side task
失败响应
{
"code": 200,
"data": {
"id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
"status": "failed",
"progress": 0,
"cost": 0,
"credits_cost": 0,
"error": {
"message": "歌词包含不允许的内容",
"type": "task_failed",
"code": "task_failed",
"param": ""
}
}
}{
"code": 200,
"data": {
"id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
"status": "failed",
"progress": 0,
"cost": 0,
"credits_cost": 0,
"error": {
"message": "The lyrics contain disallowed content",
"type": "task_failed",
"code": "task_failed",
"param": ""
}
}
}错误码
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.