音乐生成 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 余额不足

鉴权失败等通用错误见 错误码。

相关文档