Suno API

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

Base URL: https://api.routeapi.ai
认证方式: Authorization: Bearer sk-xxxx

整体工作流（先看这里）

异步模式

所有生成类操作都遵循同一个模式：提交任务拿到 ID → 轮询等结果。理解这个循环之后，其他所有接口细节都是填参数的事。

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

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

任务状态

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

3 步快速上手

第一步：提交任务

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer sk-xxxx" \
  -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 sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

第三步：取结果

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

Note

整个流程通常 10-60 秒完成。audio_url 是 CDN 直链，可直接播放或下载。

支持的模型

模型 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 字符

Tip

不确定选哪个时，用 chirp-v5-5（最新最强）。

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

POST /suno/audios

核心接口，支持全部 18 种音频创作操作。

核心参数

字段	类型	默认值	说明
model	string	chirp-v4	生成模型，推荐 chirp-v5-5
action	string	generate	操作类型，见下方说明
async	boolean	false	强烈建议设为 true，同步模式容易超时

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 sk-xxxx" \
  -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 sk-xxxx" \
  -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 sk-xxxx" \
  -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 sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "stems",
    "audio_id": "song-to-split",
    "async": true
  }'

POST /suno/tasks

查询任务状态与结果。这是查询 /suno/audios 等接口提交的任务的唯一方式。

查询单个任务

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

响应：

{
  "id": "task_xxxxx",
  "status": "success",
  "data": {
    "audio_url": "https://cdn.suno.ai/xxx.mp3",
    "video_url": "https://cdn.suno.ai/xxx.mp4",
    "title": "歌曲标题",
    "text": "歌词内容",
    "duration": 183.5,
    "model_name": "chirp-v5-5"
  }
}

批量查询

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer sk-xxxx" \
  -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 sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "写一首关于夏天和海边的中文流行歌词，要有副歌" }'

POST /suno/upload

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

curl -X POST "https://api.routeapi.ai/suno/upload" \
  -H "Authorization: Bearer sk-xxxx" \
  -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 sk-xxxx"

POST — 创建语音人格

curl -X POST "https://api.routeapi.ai/suno/persona" \
  -H "Authorization: Bearer sk-xxxx" \
  -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	提取人声片段

错误处理

状态码	说明
400	请求参数错误（必填字段缺失、格式不正确）
401	认证失败（token 无效或过期）
502	上游服务错误
500	服务器内部错误

错误响应格式：

{ "success": false, "error": "error_code", "message": "详细错误说明" }

最佳实践

轮询代码片段（JavaScript）

async function generateAndPoll(prompt) {
  // 提交任务
  const res = await fetch('https://api.routeapi.ai/suno/audios', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer sk-xxxx', '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 sk-xxxx', '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 === 'failed') throw new Error(result.error);

    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: 生成失败常见原因？

错误	原因	解法
prompt_empty	未提供 prompt 或 lyric	补充内容字段
audio_id_required	action 要求 audio_id 但未提供	检查 action 必需字段
generation_failed	内容违规或上游错误	修改提示词后重试
quota_exceeded	配额不足	检查账户余额

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