音乐生成 Suno
Suno 是异步任务接口:先提交任务拿到任务 ID,再查询任务直到完成。支持两种任务:生成歌曲(music)和生成歌词(lyrics)。
| 项 | 值 |
|---|---|
| 提交任务 | POST /suno/submit/:action,action 为 music 或 lyrics |
| 批量查询 | POST /suno/fetch |
| 单个查询 | GET /suno/fetch/:id |
| 鉴权 | Authorization: Bearer YOUR_API_KEY |
| Content-Type | application/json |
注意路径没有
/v1前缀:完整地址是https://www.nextai-code.com/suno/...。
快速示例
BASH
# 1. 提交:根据描述生成一首歌
curl https://www.nextai-code.com/suno/submit/music \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"gpt_description_prompt": "一首关于夏夜海边的轻快流行歌"}'
# => {"code":"success","message":"","data":"<task_id>"}
# 2. 查询:每隔一段时间轮询,直到 status 为 SUCCESS 或 FAILURE
curl https://www.nextai-code.com/suno/fetch/<task_id> \
-H "Authorization: Bearer $NEXTAI_API_KEY"
PYTHON
import os, time, requests
BASE = "https://www.nextai-code.com"
HEADERS = {"Authorization": f"Bearer {os.environ['NEXTAI_API_KEY']}"}
r = requests.post(f"{BASE}/suno/submit/music", headers=HEADERS,
json={"gpt_description_prompt": "一首关于夏夜海边的轻快流行歌"})
r.raise_for_status()
task_id = r.json()["data"]
while True:
task = requests.get(f"{BASE}/suno/fetch/{task_id}", headers=HEADERS).json()["data"]
if task["status"] in ("SUCCESS", "FAILURE"):
break
time.sleep(15)
print(task["status"], task.get("fail_reason"))
print(task["data"]) # 歌曲 / 歌词结果
提交任务
POST /suno/submit/:action
action |
用途 | 计价模型名 |
|---|---|---|
music |
生成歌曲(灵感模式、自定义模式、续写) | suno_music |
lyrics |
只生成歌词 | suno_lyrics |
action 不区分大小写;其他取值返回 400(message 为 invalid_action)。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
gpt_description_prompt |
string | 否 | 灵感模式:用一句话描述想要的歌曲,自动写词作曲 |
prompt |
string | lyrics 必填 |
music:自定义模式的歌词;lyrics:歌词主题描述,为空返回 400(message 为 prompt_empty) |
mv |
string | 否 | Suno 模型版本,music 未传时使用默认版本;可选版本以 模型列表 为准 |
title |
string | 否 | 歌曲标题(自定义模式) |
tags |
string | 否 | 风格标签,如 pop, upbeat(自定义模式) |
make_instrumental |
boolean | 否 | 是否生成纯音乐,默认 false |
continue_clip_id |
string | 否 | 续写:要续写的歌曲片段 ID |
continue_at |
number | 否 | 续写:从第几秒开始续写 |
task_id |
string | 续写时必填 | 续写:被续写歌曲所属的任务 ID。传了 continue_clip_id 却没传 task_id 时返回 400(task id is empty);该任务必须是本账号提交的 |
只支持以上字段,其他字段会被忽略。字段组合是否有效由 Suno 服务判断,不合法时提交会失败。
响应
JSON
{ "code": "success", "message": "", "data": "f4a2c1e0-...-task-id" }
| 字段 | 说明 |
|---|---|
code |
success 表示提交成功 |
data |
任务 ID,用于后续查询 |
查询任务
只能查询本账号提交的任务。查询本身不扣费。
单个查询
GET /suno/fetch/:id
JSON
{
"code": "success",
"message": "",
"data": {
"task_id": "f4a2c1e0-...-task-id",
"action": "MUSIC",
"status": "SUCCESS",
"fail_reason": "",
"submit_time": 1731100000,
"start_time": 1731100005,
"finish_time": 1731100090,
"progress": "100%",
"data": [ { "id": "...", "audio_url": "...", "image_url": "...", "title": "...", "status": "complete" } ]
}
}
任务 ID 不存在(或不属于本账号)时返回 400,code 为 task_not_exist。
批量查询
POST /suno/fetch
BASH
curl https://www.nextai-code.com/suno/fetch \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ids": ["<task_id_1>", "<task_id_2>"]}'
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
ids |
array | 是 | 任务 ID 列表;为空时返回空数组 |
响应的 data 是任务对象数组,字段同单个查询;不存在或不属于本账号的 ID 不会出现在结果中。
任务对象字段
| 字段 | 说明 |
|---|---|
task_id |
任务 ID |
action |
任务类型:MUSIC / LYRICS |
status |
任务状态。刚提交时为 NOT_START,之后依次变为 SUBMITTED、QUEUED、IN_PROGRESS 等,终态为 SUCCESS 或 FAILURE |
fail_reason |
失败原因 |
submit_time / start_time / finish_time |
Unix 时间戳(秒) |
progress |
进度,如 0%、100%;成功或失败后为 100% |
data |
结果数据(歌曲列表或歌词),结构与 Suno 原生返回一致,常见字段有 audio_url、video_url、image_url、title、text、metadata |
任务状态约每 15 秒更新一次,建议轮询间隔不少于 15 秒,更频繁的查询不会更快拿到结果。
计费
- 按次计费:提交成功时按
suno_music/suno_lyrics的单次价格扣费,查询不扣费。 - 提交失败不扣费。
- 任务最终
FAILURE时,已扣费用会自动退回。
错误
Suno 接口的错误体结构与其他接口不同:
JSON
{ "code": "invalid_request", "message": "invalid_action", "data": null }
| HTTP | code |
说明 |
|---|---|---|
| 400 | invalid_request |
action 非法、lyrics 缺少 prompt、续写缺少 task_id,或请求体不是合法 JSON |
| 400 | task_not_exist |
查询或续写的任务不存在 / 不属于本账号 |
| 400 | pricing_not_configured |
该任务类型暂不可用,请联系客服 |
| 402 | quota_not_enough |
余额不足 |
鉴权失败等通用错误见 错误码。
相关文档
- 语音合成
- Midjourney(同为提交→查询的异步任务)
- 错误码