NearToken

外观

Suno 音乐 ​

Suno 采用异步任务：先提交取得任务 ID，再查询状态。任务结果保持上游返回的字段原样。

音乐与歌词是两个独立能力，分别对应模型标识 suno_music 和 suno_lyrics。模型标识用于令牌授权与计费，不需要写进请求体。

鉴权与地址 ​

所有请求都用 Bearer 令牌：

http
Authorization: Bearer sk-你的令牌
Content-Type: application/json
操作方法与路径
生成音乐POST /suno/submit/music
生成歌词POST /suno/submit/lyrics
查询单个任务GET /suno/fetch/{task_id}
批量查询任务POST /suno/fetch

路径不带 /v1。令牌需要 Suno满血1x 分组，并包含目标模型的权限。

生成音乐 ​

bash
curl -sS -X POST "$ROOT_URL/suno/submit/music" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "[Verse]\n夜色落在海面，晚风吹过城市\n[Chorus]\n我们追逐夏日潮汐",
    "tags": "mandopop, female vocal, upbeat",
    "title": "夏日潮汐",
    "mv": "chirp-v5",
    "make_instrumental": false
  }'

提交成功后立即返回平台任务 ID：

json
{"code": "success", "message": "success", "data": "xxx"}

data 就是这个任务的任务 ID。返回成功只代表任务进入队列。

三种创作方式 ​

灵感生成：只给主题和情绪，由模型补全歌词。用 gpt_description_prompt。

json
{
  "gpt_description_prompt": "一首关于夏日海边的轻快华语流行歌，女声，充满旅行感",
  "mv": "chirp-v5"
}

自定义歌词：用 prompt 传带结构标签的歌词（[Intro]、[Verse]、[Chorus]、[Bridge] 等），最多 3000 字。

纯音乐：make_instrumental 设为 true。

音乐参数 ​

参数必填说明
gpt_description_prompt条件必填灵感生成描述；与 prompt、纯音乐或续写至少提供一种
prompt条件必填歌词内容，支持结构标签，最多 3000 字
tags否风格，例如 mandopop, female vocal, upbeat
title否作品标题
mv否模型版本：chirp-v4、chirp-v4-5、chirp-v5、chirp-v5-5 等
make_instrumental否是否纯音乐，默认 false
task_id续写必填原音乐任务的 ID
continue_clip_id续写必填原任务结果里的作品 clip ID
continue_at续写必填从第几秒开始续写，可以为 0
callback_url否任务进入终态后接收 POST 回调的公网地址

mv 不写死成枚举，上游新增版本时可以直接传。

生成歌词 ​

bash
curl -sS -X POST "$ROOT_URL/suno/submit/lyrics" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "一首关于深夜通勤的华语流行歌，主题是疲惫与坚持"}'

歌词任务的 prompt 必填。返回同样是任务 ID。

查询结果 ​

bash
curl -sS "$ROOT_URL/suno/fetch/xxx" -H "Authorization: Bearer $API_KEY"

状态流转：

text
QUEUED → SUBMITTING → IN_PROGRESS → SUCCESS
                              ↘ FAILURE
状态客户端处理
QUEUEDworker 尚未取走任务，继续查询
SUBMITTING平台正在提交上游，继续查询
IN_PROGRESS生成中，继续查询
SUCCESS停止轮询，读取 data.data
FAILURE停止轮询，读取 fail_reason

歌词任务不经过 IN_PROGRESS：上游歌词接口是同步的，worker 拿到结果后直接置为 SUCCESS。

建议每 5～10 秒查询一次，不要高频轮询。

音乐生成成功的响应：

json
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "xxx",
    "platform": "suno",
    "action": "MUSIC",
    "status": "SUCCESS",
    "fail_reason": "",
    "data": [
      {
        "clipId": "clip-id",
        "audio_url": "https://example.com/song.mp3",
        "image_url": "https://example.com/cover.jpg",
        "duration": 30.28,
        "prompt": "[Verse]..."
      }
    ]
  }
}

data.data 是候选作品数组，字段保持上游原样，可能随上游增加。按需读取作品 ID、音频地址、封面地址和歌词即可，不要因为出现未知字段而拒绝整个响应。音频链接有时效，拿到后请及时保存。

批量查询 ​

批量查询只接受平台任务 ID，不接受作品 clip ID：

bash
curl -sS -X POST "$ROOT_URL/suno/fetch" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["xxx", "yyy"]}'

响应 data 是任务数组，每项带 task_id、status、progress 等字段，已完成的任务带 data。

计费与限制 ​

  • 生成音乐按歌曲计费，生成歌词按次计费；具体价格以控制台模型广场和账单为准。
  • 音乐可能只成功一部分作品。部分成功时保留可用作品，不要重新生成整单。
  • 当前开放音乐与歌词两项能力。音效生成、人声/伴奏分离、时间线查询暂未开放，对应的 suno_sound、suno_stems_by_url、suno_timing 模型标识在控制台中可见但没有可用的提交通道。
  • 超时或网络中断后先查控制台使用日志，再决定是否重试。

NearToken