【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当前文档列出的版本值如下UI 文案model_versionV5.5 (Latest)V5_5V5V5V4.5 PlusV4_5PLUSV4.5 AllV4_5ALLV4.5V4_5V4V4本地历史实测文件suno_channel258_generate_versions_20260624.json记录了2026-06-24 08:00对 258 渠道的逐版本测试suno/generate主链当时全部成功versionstatusformatV5_5succeededmp4V5succeededmp4V4_5PLUSsucceededmp4V4_5ALLsucceededmp4V4_5succeededmp4V4succeededmp4这说明generate主链在当时的 258 渠道上是可用的。注意统一任务查询层可能显示formatmp4但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_id4. 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-extend5. 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_id6. 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/* 任务接口和其他视频/音频任务更一致 更容易接入统一任务队列 更适合做多模型路由、回调、日志和重试但迁移老项目时要注意字段差异项目老路由新统一接口版本字段mvmodel_version提交路径/suno/submit/music/v1/video/generations查询路径/suno/fetch/{task_id}/v1/video/generations/{task_id}模型名路由决定suno/generate等结果字段可能偏 Suno 原生当前部分路由可能只稳定返回 task/url9. 生产接入架构建议不要把 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. 上线前测试用例最少要测这些用例期望suno/generateV5_5返回 task_id能轮询到终态suno/generateV5返回 task_id能轮询到终态错误 API Key返回鉴权错误错误模型名返回明确错误纯input写法记录当前生产返回顶层prompt metadata写法记录当前生产返回内容 URL 或 audio_url 下载HTTP 200 媒体类型公开内容 URL 失败但 audio_url 成功使用 audio_url 或服务端代理转发内容 URL 和 audio_url 都失败状态进入content_unavailableextend无 audioId前端不展示或服务端拒绝vocal-separation缺 taskId返回参数错误不进入死循环如果你只测“提交成功”上线后一定会遇到更多不可解释的问题。12. FAQQ1产品里应该默认展示哪些 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并不等于最终媒体文件可用。生产系统要把这个差异设计进去。