Suno API

RouteAPI 提供统一的 Suno AI 音乐生成 REST API。支持文本生成音乐、续写歌曲、声音克隆、音轨分离等功能。

整体工作流（先看这里）

Suno 音乐生成是异步的。 典型流程：

提交任务 到 /suno/audios → 收到 task_id
等待 2-3 秒 后开始轮询
每 3-5 秒轮询一次 通过 /suno/tasks 使用 action: "retrieve"
当 status 变为 success → 获取 audio_url

任务状态

状态	含义	下一步
`submitted`	已提交，等待排队	继续轮询
`queued`	排队中	继续轮询
`in_progress`	生成中	继续轮询
`success`	✅ 完成	从 `data` 数组的第一项取 `audio_url`
`failure`	❌ 失败	取 `error` 字段查原因

3 步快速上手

第一步：提交任务

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "prompt": "一首欢快的夏日流行歌曲，钢琴和吉他",
    "async": true
  }'

响应：

{ "success": true, "task_id": "task_xxxxx" }

第二步：轮询任务状态

每 3-5 秒查一次，直到 status 变为 success：

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

第三步：取结果

{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "status": "success",
  "data": [
    {
      "id": "audio_1",
      "audio_url": "https://cdn.suno.ai/xxx.mp3",
      "video_url": "https://cdn.suno.ai/xxx.mp4",
      "title": "Summer Breeze",
      "duration": 183.5
    }
  ]
}

支持的模型

模型 ID	最长时长	lyric 上限	style 上限	title 上限
`chirp-v5-5`	8 分钟	5000 字符	1000 字符	100 字符
`chirp-v5`	8 分钟	5000 字符	1000 字符	100 字符
`chirp-v4-5-plus`	8 分钟	5000 字符	1000 字符	100 字符
`chirp-v4-5`	4 分钟	5000 字符	1000 字符	100 字符
`chirp-v4`	150 秒	3000 字符	200 字符	80 字符
`chirp-v3-5`	120 秒	3000 字符	200 字符	80 字符

prompt（非 custom 模式）各模型统一限制 500 字符。

POST /suno/audios

音频操作的核心接口：action 字段决定具体操作，请求体携带该操作需要的字段。

核心参数

字段	类型	默认值	说明
`model`	string	`chirp-v4`	生成模型，推荐 `chirp-v5-5`
`action`	string	`generate`	操作类型，见下方说明
`async`	boolean	—	强烈建议设为 `true`，同步模式容易超时。只有显式传 `false` 才走同步分支；省略该字段时不会转发，由上游默认值决定

Action 操作类型

Action	说明	必需字段
`generate`	根据提示词生成全新音频	`prompt` 或 `custom=true` + `lyric` + `style`
`extend`	在已有音频基础上续写延长	`audio_id` + `continue_at`
`concat`	将已有音频片段拼接为完整曲目	`audio_id`
`cover`	复制已有曲目的音乐风格并重新演绎	`audio_id`
`upload_cover`	对已上传音频进行风格翻唱	`audio_id`（需先 `/suno/upload`）
`upload_extend`	将已上传音频延伸续生成	`audio_id` + `continue_at`
`artist_consistency`	以指定 Persona 的歌手风格演唱新歌曲	`persona_id` + `lyric` / `prompt`
`artist_consistency_vox`	以 VOX 模式使用指定 Persona 演唱（更高质量）	`persona_id` + `lyric` / `prompt`
`stems`	分离为人声 + 伴奏两轨	`audio_id`
`all_stems`	分离为所有独立音轨（人声、鼓、贝斯、其他）	`audio_id`
`replace_section`	替换指定时间段内的音频片段	`audio_id` + `replace_section_start` + `replace_section_end`
`underpainting`	为已上传人声轨道生成并添加 AI 伴奏	`audio_id` + `underpainting_start` + `underpainting_end`
`overpainting`	为已上传伴奏轨道生成并添加 AI 人声	`audio_id` + `overpainting_start` + `overpainting_end`
`samples`	在指定时间段内添加 AI 采样	`audio_id` + `samples_start` + `samples_end`
`remaster`	对已有音频重新母带处理以提升音质	`audio_id`
`mashup`	将多首歌曲混合拼接为一首曲目	`mashup_audio_ids`（数组）
`inspo`	以 1-4 段参考音频为灵感生成全新音乐	`audio_urls`（1-4 个 URL）

内容创作参数

字段	类型	说明
`prompt`	string	音乐主题、情绪、场景的自然语言描述
`lyric`	string	自定义歌词正文，支持段落标记如 `[Verse]`、`[Chorus]`、`[Bridge]` 等
`custom`	boolean	开启自定义模式，允许指定歌词、标题、风格
`instrumental`	boolean	生成纯音乐（无人声）
`title`	string	歌曲标题
`style`	string	风格、流派、情绪描述，多个用逗号分隔
`style_negative`	string	不希望出现的风格
`duration`	integer	期望歌曲时长（秒，10-360），仅 `custom: true` 时有效，倾向提示

音频操作参数

字段	类型	说明
`audio_id`	string	已有音频 ID（来自生成结果或通过 `/suno/upload` 上传）
`audio_urls`	string[]	参考音频公网 URL 列表（1-4 个）
`mashup_audio_ids`	string[]	混音源音频 ID 列表
`continue_at`	number	续写起始时间点（秒）

声音与人格参数

字段	类型	说明
`persona_id`	string	语音人格 ID，通过 `/suno/persona` 创建
`vocal_gender`	string	人声性别偏好：`f`（女声）/ `m`（男声）
`variation_category`	string	remaster 精细度：`high` / `normal` / `subtle`

示例

描述词快速生成

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "prompt": "一首欢快的儿童歌曲，关于小黄鸭在池塘游泳",
    "async": true
  }'

自定义歌词生成

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "custom": true,
    "title": "小黄鸭之歌",
    "style": "儿歌, 欢快, 轻快",
    "lyric": "[Verse]\n小黄鸭呀水里游\n摇摇摆摆不停留\n[Chorus]\n嘎嘎嘎呀真自由\n快快乐乐向前走",
    "async": true
  }'

续写音乐（extend）

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5",
    "action": "extend",
    "audio_id": "abc123-audio-id",
    "continue_at": 30.5,
    "async": true
  }'

音轨分离（stems）

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "stems",
    "audio_id": "song-to-split",
    "async": true
  }'

POST /suno/tasks

查询任务状态与结果。这是查询 /suno/audios 等接口提交的任务的主要方式。POST /suno/fetch（批量）与 GET /suno/fetch/{id} 会以另一种外层结构返回同样的记录；提交时若传了 callback_url，RouteAPI 还会在任务进入终态后把完成通知（task_id、status、fail_reason、data）POST 到该地址。

查询单个任务

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

响应：

{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "status": "success",
  "data": [
    {
      "id": "audio_1",
      "audio_url": "https://cdn.suno.ai/xxx.mp3",
      "video_url": "https://cdn.suno.ai/xxx.mp4",
      "title": "歌曲标题",
      "text": "Lyrics content",
      "model_name": "chirp-v5-5",
      "duration": 183.5
    }
  ]
}

任务记录的 data 保存上游结果。歌曲生成通常是片段数组；个别操作（例如 /suno/upload）返回单个对象，因此读取 data 时要按「数组或单个对象」处理，而不是无条件取下标。终态记录还会带 created_at、started_at、finished_at、elapsed、清洗后的 response 与提交的 request。

批量查询

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve_batch", "ids": ["task_001", "task_002"] }'

POST /suno/lyrics

生成歌词文本，结果可直接用于 /suno/audios 的 lyric 字段。

curl -X POST "https://api.routeapi.ai/suno/lyrics" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "写一首关于夏天和海边的中文流行歌词，要有副歌" }'

POST /suno/upload

上传外部音频文件，返回 audio_id，用于续写、变体、声音克隆等后续操作。

curl -X POST "https://api.routeapi.ai/suno/upload" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audio_url": "https://example.com/my-audio.mp3" }'

GET/POST /suno/persona

管理语音人格（声音克隆）。

GET — 获取人格列表

curl -X GET "https://api.routeapi.ai/suno/persona" \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

POST — 创建语音人格

curl -X POST "https://api.routeapi.ai/suno/persona" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "uploaded-audio-id",
    "name": "温柔女声",
    "vocal_start": 5.0,
    "vocal_end": 15.0
  }'

其他接口

接口	方法	说明
`/suno/voices`	POST	从音频中提取人声信息
`/suno/style`	POST	生成风格描述文本
`/suno/mashup-lyrics`	POST	混合两段歌词
`/suno/wav`	POST	导出 WAV 格式音频（30 天有效期）
`/suno/mp4`	POST	导出 MP4 视频
`/suno/midi`	POST	导出 MIDI 文件
`/suno/timing`	POST	获取音频时序信息
`/suno/vox`	POST	提取人声片段

错误处理

请求进入任务处理后，错误使用任务响应体：

{ "code": "invalid_request", "message": "prompt_empty (request id: ...)", "data": null }

认证与路由阶段的失败发生在进入任务处理之前，沿用 OpenAI 风格响应体 {"error": {"message": "...", "type": "...", "code": "..."}}。参见常见错误。

状态码	错误码	原因
400	`invalid_request`	该接口或 action 缺少必填字段，`message` 会指明字段（例如 `/suno/lyrics` 的 `prompt_empty`，或 `/suno/vox` 的 `audio_id_vocal_start_vocal_end_required`）
400	`task_not_exist`	`action: "retrieve"` 的 `id` 不属于你的任务
401	—	API Key 缺失、无效或已过期（OpenAI 风格响应体）
403	`insufficient_user_quota`	账户余额或 Key 额度不足以预扣
429	—	上游渠道报告限流或过载；RouteAPI 会替换供应商原文
502	`acedata_suno_request_failed`	上游已受理但拒绝了请求：内容审核拦截、`audio_id` 不存在、不支持的 action。`message` 带上游说明
502	`upstream_task_id_missing`	上游返回 2xx 但没有任务 ID，任务无法轮询；预扣费用会退回
503	`get_channel_failed`	任务背后的渠道被判为硬故障（例如上游账户不可用）；RouteAPI 会替换供应商原文。（完全没有渠道的模型会在进入任务处理前就被拒绝，返回 `503 model_not_found` 与 OpenAI 风格响应体）
4xx / 5xx	`fail_to_fetch_task`	上游返回非 2xx 状态码；状态码与响应体原样透传，预扣费用退回

轮询返回 failure 的失败任务同样会退回预扣费用，失败原因在任务记录的 error 与 message 字段中。

最佳实践

轮询代码片段（JavaScript）

async function generateAndPoll(prompt) {
  // 提交任务
  const res = await fetch('https://api.routeapi.ai/suno/audios', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer $ROUTEAPI_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({ model: 'chirp-v5-5', prompt, async: true })
  });
  const { task_id } = await res.json();

  // 轮询，首次先等 3 秒
  await new Promise(r => setTimeout(r, 3000));

  const deadline = Date.now() + 3 * 60 * 1000; // 3 分钟超时
  while (Date.now() < deadline) {
    const poll = await fetch('https://api.routeapi.ai/suno/tasks', {
      method: 'POST',
      headers: { 'Authorization': 'Bearer $ROUTEAPI_KEY', 'Content-Type': 'application/json' },
      body: JSON.stringify({ action: 'retrieve', id: task_id })
    });
    const result = await poll.json();

    if (result.status === 'success') return result.data;
    if (result.status === 'failure') throw new Error(result.error || result.message);

    await new Promise(r => setTimeout(r, 4000)); // 每 4 秒轮询一次
  }
  throw new Error('Task timeout');
}

常见问题 FAQ

Q: 如何选择模型版本？
优先用 chirp-v5-5（最新最强）。需要更稳定的老版本选 chirp-v4。

Q: 生成需要多久？
generate 通常 15-40 秒。stems、all_stems、remaster 等处理类操作可能更长（1-3 分钟）。

Q: audio_url 可以直接用吗？
是的，CDN 直链可直接播放或下载：curl -o song.mp3 "<audio_url>"

Q: 单次 generate 生成多长时间的音乐？
通常 2-3 分钟。用 extend 可以续写到 4-5 分钟甚至更长。

Q: 生成失败常见原因？

`message` / 错误码	原因	解法
`prompt_empty`（`invalid_request`）	`/suno/lyrics` 或 `/suno/style` 未提供 `prompt`	补充提示词
`audio_id_required`（`invalid_request`）	`/suno/wav`、`/suno/mp4`、`/suno/midi` 或 `/suno/timing` 未提供 `audio_id`	传入生成时返回的音频 ID
`acedata_suno_request_failed`（502）	上游拒绝了提交的任务，常见为内容审核拦截或 `audio_id` 不存在	阅读 `message` 中的上游说明，调整请求后重试
轮询状态 `failure`	任务受理后执行失败，原因在任务记录的 `error` / `message` 中	调整提示词后重试；预扣费用已退回
`insufficient_user_quota`（403）	账户余额或 Key 额度不足以预扣	充值或提高 Key 额度

Q: 并发请求有限制吗？
有，取决于账户套餐。建议并发数 ≤ 5，轮询间隔 ≥ 3 秒。