【Suno SDK 系列 03】Suno SDK 模型族怎么选？generate、extend、cover、时间轴歌词、人声分离生产接入指南

【Suno SDK 系列 03】Suno SDK 模型族怎么选？generate、extend、cover、时间轴歌词、人声分离生产接入指南

适合读者：已经了解 Suno 基础生成，准备把多种音乐能力接进产品的工程团队。
文章重点：按生产视角拆解suno/generate、suno/extend、suno/upload-extend、suno/cover、suno/timestamped-lyrics、suno/vocal-separation，并说明哪些能力必须单独实测。

先说结论

Crazyrouter 文档里的 Suno SDK 不是一个单一模型，而是一组统一任务模型族。

当前文档列出的模型包括：

suno/generate suno/extend suno/upload-extend suno/cover suno/timestamped-lyrics suno/vocal-separation

统一入口是：

POST /v1/video/generations GET /v1/video/generations/{task_id} GET /v1/videos/{task_id}/content

如果只接一个能力，优先从suno/generate开始。

如果要接完整产品功能，建议按这个顺序：

1. suno/generate：先跑通文本生成音乐 2. 媒体 URL：确认 `content url` 或 `resultJson.data[0].audio_url` 能下载和播放 3. 结果字段：确认是否有 audioId、audioUrl、audio_url、taskId 4. suno/extend：基于已有 Suno 音频续写 5. suno/upload-extend：基于外部音频续写 6. suno/cover：翻唱或风格改写 7. timestamped-lyrics / vocal-separation：最后接，且必须单独验证字段

原因很简单：后面这些派生能力通常依赖前一次生成结果里的字段，比如audioId、audioUrl、taskId。如果基础结果里没有稳定透出这些字段，派生能力就不能直接上线。

1. 版本参数：不要把 mv 和 model_version 混用

文档里明确说，Suno 统一任务模型族使用：

input.model_version

不是老/suno/submit/music路由里的：

mv

当前文档列出的版本值如下：

本地历史实测文件suno_channel258_generate_versions_20260624.json记录了2026-06-24 +08:00对 258 渠道的逐版本测试，suno/generate主链当时全部成功：

这说明generate主链在当时的 258 渠道上是可用的。注意：统一任务查询层可能显示format=mp4，但2026-07-06对task_ac90b23619334516的进一步复测表明，真实 Suno 媒体文件来自resultJson.data[0].audio_url，实际Content-Type是audio/mp3。

但注意，这不等价于所有派生能力都稳定可用，也不等价于你今天的自动路由一定完全一样。上线前仍然要用自己的 Key 复测。

2. suno/generate：文本生成音乐，最适合第一步接入

suno/generate是最基础、最应该先跑通的模型。

适合场景：

输入歌词生成歌曲 输入音乐描述生成歌曲 生成短广告音乐 生成 demo 歌曲 生成产品里的示例音乐

常用参数：

model_version prompt customMode instrumental style title

文档示例使用的是input：

{"model":"suno/generate","channel":"auto","input":{"model_version":"V5_5","customMode":true,"instrumental":false,"prompt":"[Verse]\nMorning lights across the wire","style":"bright synth pop, short, clean vocals","title":"CR Suno Route Test"}}

但我在2026-07-06 +08:00的生产实测中，纯input写法返回：

{"code":"invalid_request","message":"prompt is required","data":null}

当时可提交成功的是顶层prompt + metadata写法：

{"model":"suno/generate","prompt":"[Verse]\n清晨的键盘亮起光\n请求穿过云端的墙","metadata":{"model_version":"V5_5","customMode":true,"instrumental":false,"prompt":"[Verse]\n清晨的键盘亮起光\n请求穿过云端的墙","style":"bright synth pop, short, clean vocals, Mandarin pop","title":"Crazyrouter Suno SDK Smoke Test 20260706"}}

提交成功后返回：

{"id":"task_ac90b23619334516","task_id":"task_ac90b23619334516","object":"video","model":"suno/generate","status":"queued"}

轮询后返回：

{"code":"success","data":{"status":"succeeded","format":"mp4","task_id":"task_ac90b23619334516","url":"https://crazyrouter.com/v1/videos/task_ac90b23619334516/content"}}

生产建议：

先只接 generate 只开放少量版本选项 先用短歌词测试 记录 task_id 记录完整响应 不要跳过内容 URL 校验

3. suno/extend：基于已有 Suno 音频续写

suno/extend用来续写已有 Suno 生成的音频。

适合场景：

把 30 秒 demo 扩展成完整歌曲 给已有歌曲加 bridge 给已有副歌继续生成 outro 做多个版本的长短变体

常用参数：

model_version audioId continueAt prompt style title instrumental

示例：

{"model":"suno/extend","channel":"auto","input":{"model_version":"V5","audioId":"abc123-def456","continueAt":20,"instrumental":false,"prompt":"[Bridge]\nCarry the melody forward with a brighter chorus and soft harmonies","style":"bright synth pop, clean vocals","title":"CR Suno Route Test Extended"}}

关键点是audioId。

如果你的suno/generate查询结果只返回：

{"status":"succeeded","url":"https://crazyrouter.com/v1/videos/task_xxx/content"}

但没有返回音频项里的audioId，那么extend就不能直接接。

文档里也提醒：部分 Suno 路由查询结果只稳定返回task_id、status、url，不一定总能回出audioId。

生产建议：

先检查 generate 结果是否稳定包含 audioId 没有 audioId 时不要开放 extend 按钮 continueAt 不要让用户随便填，前端做范围限制 续写任务要单独记录 source_task_id 和 source_audio_id

4. suno/upload-extend：基于外部音频 URL 续写

suno/upload-extend和extend的区别是：它不一定要求来源必须是 Suno 内部生成结果，而是基于外部音频 URL 继续生成。

适合场景：

用户上传一段旋律后续写 把对象存储里的音频继续扩展 给已有素材生成 outro

常用参数：

model_version audioUrl continueAt prompt style title

示例：

{"model":"suno/upload-extend","channel":"auto","input":{"model_version":"V4_5PLUS","audioUrl":"https://your-storage.example.com/source.mp3","continueAt":20,"instrumental":false,"prompt":"Extend with a simple upbeat outro","style":"bright synth pop","title":"Upload Extend Demo"}}

这里最容易出问题的是audioUrl。

上线前必须验证：

URL 是否公网可访问 是否需要签名 签名是否足够长 Content-Type 是否正确 文件大小是否合理 音频时长是否符合上游要求 是否允许上游服务访问你的对象存储域名

不要直接把用户上传临时地址传给上游。更稳的方式是：

用户上传 后端转存到自己的对象存储 后端生成可访问的临时 URL 再提交 upload-extend

5. suno/cover：翻唱或风格改写

suno/cover用来基于已有音频做翻唱或风格改写。

适合场景：

同一首歌生成不同风格版本 把流行风改成 acoustic pop 把 demo 改成广告音乐版本 生成男女声不同版本

常用参数：

model_version audioUrl customMode instrumental prompt style title vocalGender

示例：

{"model":"suno/cover","channel":"auto","input":{"model_version":"V4_5ALL","audioUrl":"https://your-storage.example.com/original.mp3","customMode":false,"instrumental":false,"prompt":"Transform into an acoustic pop cover with gentle guitar","style":"acoustic pop","title":"Acoustic Cover Demo","vocalGender":"f"}}

本地 2026-06-24 的完整测试里，cover使用由generate返回的内容 URL 做输入，任务提交成功，但最终返回过：

Service temporarily unavailable. Please try again later.

这类派生能力更依赖上游状态、输入 URL、音频字段和渠道可用性，所以不要因为generate成功，就默认cover一定成功。

生产建议：

cover 单独做渠道级 smoke test 输入 URL 先做可下载校验 不要在用户界面承诺 100% 成功 失败时保留原音频和 cover task_id

6. suno/timestamped-lyrics：时间轴歌词

suno/timestamped-lyrics用来获取时间轴歌词。

适合场景：

歌词逐字/逐句高亮 音乐播放器同步字幕 短视频歌词卡点 歌词编辑器

常用参数：

taskId audioId

示例：

{"model":"suno/timestamped-lyrics","channel":"auto","input":{"taskId":"task_xxx","audioId":"audio_xxx"}}

注意，时间轴歌词不是只要有task_id就一定能拿到。它通常还需要audioId。

文档中也记录了历史复测观察：timestamped-lyrics在 258 渠道上曾出现过metadata写法 400、input写法上游 502 的情况。

生产建议：

只有 generate 返回 audioId 后才展示“生成时间轴歌词” 失败时不要影响主歌曲下载 把歌词任务作为派生任务单独存储 歌词结果要允许用户重新生成或手动编辑

7. suno/vocal-separation：人声与伴奏分离

suno/vocal-separation用来做人声和伴奏分离。

适合场景：

提取伴奏 提取人声 做二次混音 给剪辑工具提供素材

文档里建议的稳妥参数集合是：

taskId audioId audioUrl

示例：

{"model":"suno/vocal-separation","channel":"auto","input":{"taskId":"task_xxx","audioId":"audio_xxx","audioUrl":"https://your-storage.example.com/source.mp3","prompt":"Separate vocals and instrumental stems"}}

本地历史测试里，只传audioUrl曾返回：

taskId is required

所以不要偷懒只传一个 URL。生产上建议把三类字段都准备好：

原始任务 ID 音频 ID 可下载音频 URL

如果其中一个字段缺失，就把按钮置灰或提示“当前结果不支持人声分离”。

8. 老 /suno/submit/music 和新统一接口怎么选

旧接口形态类似：

POST /suno/submit/music GET /suno/fetch/{task_id}

新文档推荐的是统一任务模型族：

POST /v1/video/generations GET /v1/video/generations/{task_id}

新项目建议优先按新接口接。

原因：

模型名统一为 suno/* 任务接口和其他视频/音频任务更一致 更容易接入统一任务队列 更适合做多模型路由、回调、日志和重试

但迁移老项目时要注意字段差异：

9. 生产接入架构建议

不要把 Suno 任务写成一个同步接口：

前端请求 -> 后端等待生成 -> 返回文件

更稳的架构是：

前端提交生成请求 后端创建本地 job 后端调用 Crazyrouter submit 保存 task_id 和原始响应 后台 worker 轮询任务 任务 succeeded 后下载并验证内容 转存到自己的对象存储 前端轮询本地 job 状态

这样做的好处：

不会让用户请求超时 可以做失败重试 可以保存完整证据 可以转存稳定下载链接 可以统一计费和审计

10. 数据库字段建议

如果你要做生产系统，可以给任务表设计这些字段：

id user_id model model_version prompt style title source_task_id source_audio_id source_audio_url provider_task_id provider_status provider_response_json content_url content_http_status content_type content_bytes storage_url error_code error_message created_at updated_at finished_at

派生任务还要记录关系：

parent_job_id job_type: generate | extend | cover | lyrics | separation

这样当用户说“我的翻唱失败了”，你能查到它依赖的是哪一次生成、哪个音频 ID、哪个 URL。

11. 上线前测试用例

最少要测这些：

如果你只测“提交成功”，上线后一定会遇到更多不可解释的问题。

12. FAQ

Q1：产品里应该默认展示哪些 Suno 能力？

建议第一版只展示generate。等你确认结果里稳定有audioId或audio_url，且真实媒体 URL 可下载，再开放extend、cover、时间轴歌词和人声分离。

Q2：多个版本都要开放给用户吗？

不建议一开始全放开。可以先默认V5_5，高级设置里再给V5或V4_5PLUS。版本越多，测试矩阵越大。

Q3：如果generate成功但没有audioId怎么办？

不要强行调用extend或timestamped-lyrics。可以把这次结果视为“只能下载/播放，不支持派生能力”。

Q4：内容 URL 下载失败是否要自动重试？

建议重试。比如 0 秒、10 秒、30 秒、60 秒各试一次。公开/content仍失败时，要继续检查resultJson.data[0].audio_url；如果audio_url也失败，再标记content_unavailable，保留task_id供人工排查。

Q5：为什么文章里反复强调实测？

因为 Suno 这类能力涉及异步任务、上游状态、渠道、内容文件、派生字段。只看文档很容易忽略“任务成功但公开代理不可下载，但上游 audio_url 可下载”或“主链成功但派生字段缺失”这类生产问题。

最后总结

Suno SDK 模型族可以按能力分成三层：

基础层：suno/generate 派生创作层：suno/extend、suno/upload-extend、suno/cover 分析处理层：suno/timestamped-lyrics、suno/vocal-separation

接入顺序不要反过来。

最稳的路线是：

先跑通 generate 再验证内容 URL 再确认 audioId/audioUrl/taskId 字段 最后开放派生能力

本文所有建议都来自文档读取和本地实测记录。特别是2026-07-06的测试说明了一点：succeeded并不等于最终媒体文件可用。生产系统要把这个差异设计进去。