suno-cn-music

# 🎵 Suno.cn AI 音乐助手 通过 HTTP REST API 调用 Suno.cn 音乐生成服务。 --- ## ⛔ 强制规则（违反任何一条即为错误） 1. **只能使用下方定义的 HTTP REST API**。绝对不要尝试 MCP JSON-RPC、WebSocket 或任何其他协议。 2. **所有 API 调用必须使用 HTTP 请求**（GET/POST），Base URL 固定为 https://mcp.suno.cn，不要猜测或尝试其他端点。 3. **严禁编造 API 响应**。如果 API 调用失败，直接告诉用户"调用失败"并附上错误信息，不要编造结果或提供"手动操作指南"。 4. **严禁改写 API 返回的内容**。歌词、歌曲标题等必须原样展示，不要总结、翻译、改写或省略。 5. **严禁在 API 调用失败时建议用户去网页手动操作**。只需报告错误，让用户检查 API Key 或稍后重试。 6. **不要使用 web_fetch、curl 或任何网页抓取工具来调用这些 API**。只使用标准 HTTP 请求工具。 7. **严禁对 API Key 进行任何格式校验**（包括长度、字符类型、结构等）。无论 key 看起来多么"奇怪"，都必须直接调用 API 验证。不要试图"帮助"用户预判 key 是否正确。 8. **严禁添加 skill 文档中未提及的"优化"或"帮助"**。不要自行重试、不要自行解释错误原因、不要提供文档未规定的建议。 --- ## 第一步：配置 API Key 设置环境变量 `SUNO_CN_API_KEY`： - **Linux/macOS**: `export SUNO_CN_API_KEY=sk-xxx` - **Windows PowerShell**: `$env:SUNO_CN_API_KEY="sk-xxx"` - **Windows CMD**: `set SUNO_CN_API_KEY=sk-xxx` - **Docker**: `-e SUNO_CN_API_KEY=sk-xxx` - **.env 文件**: 写入 `SUNO_CN_API_KEY=sk-xxx` ⚠️ 任何能设置环境变量的方式都可以，不依赖特定平台。 ### 获取 API Key 1. 访问 https://www.suno.cn/home/#/mcp 2. 登录后点击「AI 助手接入」→「创建新密钥」 3. 复制 `sk-` 开头的密钥 4. ⚠️ 立刻保存，关闭后无法再查看 --- ## 第二步：开始创作 对话示例： - 「帮我生成一首关于夏天的流行歌曲」 - 「查一下刚才的歌好了吗」 - 「显示我最近的音乐列表」 - 「获取这首歌的歌词」 --- ## API 调用规范 **Base URL**: `https://mcp.suno.cn` **认证 Header**: `Authorization: Bearer ${SUNO_CN_API_KEY}` **格式**: JSON **编码**: UTF-8（请求体必须使用 UTF-8 编码，中文直接传入） **网络**: 自动使用系统代理（HTTP_PROXY/HTTPS_PROXY） **超时**: 默认 30 秒，查询任务状态可延长至 60 秒 ⚠️ 重要：这是标准 HTTP REST API，不是 MCP JSON-RPC。直接发 HTTP 请求即可。 --- ## ⚠️ 调用前自检（每次对话必须逐项确认） 在调用任何 API 之前，请在心中默念： - [ ] 我有 SUNO_CN_API_KEY 吗？ → 没有：引导用户获取，不要尝试调用 API - [ ] 用户的要求能用现有 API 实现吗？ → 不能：直接说"抱歉，当前不支持此功能"，不要编造 - [ ] 我知道每个参数的含义和必填性吗？ → 不确定：查阅 API 文档，不要猜测 - [ ] 我准备好处理可能的错误了吗？ → 没有：先阅读"错误处理流程"章节 任何一项为"否"，都不要继续调用 API。 --- ## API 1：查询账户信息 用途：用户询问积分、余额、会员状态时调用。 请求：GET https://mcp.suno.cn/mcp/api/user Header：Authorization: Bearer ${SUNO_CN_API_KEY} 响应字段：nickname（昵称）、points（积分）、vip_status（会员状态） ⚠️ 响应中的中文可能显示乱码，这是终端编码问题，不是 API 错误，原样展示即可。 --- ## API 2：生成音乐 用途：用户想创作/生成音乐时调用。 ### 调用决策树（严格按此流程执行） ` 当用户表达 [生成歌曲] [创作音乐] [写首歌] [做首曲子] 等意图时： 步骤 1：确认需求 IF 用户提供了歌词： custom_mode = true prompt = 用户提供的完整歌词 ELSE IF 用户描述了音乐风格（如"夏天的流行歌"）： custom_mode = false prompt = 用户的描述（AI 模式，由服务端生成歌词） ELSE: 询问用户："请提供歌词，或描述您想要的音乐风格（例如：帮我生成一首关于夏天的流行歌曲）" → 停止，等待用户回复 步骤 2：构建请求 request = { method: "POST", url: "https://mcp.suno.cn/mcp/api/generate", headers: { "Authorization": "Bearer ${SUNO_CN_API_KEY}", "Content-Type": "application/json; charset=utf-8" }, body: { prompt: 步骤 1 中确定的描述或歌词， mv: 用户指定的版本 || "chirp-fenix", title: 用户指定的标题 || 不传， tags: 用户指定的风格（必须使用英文，如 "pop, folk, c-pop"） || 不传， custom_mode: 有歌词则为 true，否则为 false, instrumental: 用户要求纯音乐则为 true || false } } 步骤 3：发送请求并处理响应 response = send(request) IF response.status == 200: serialNos = response.serial_nos message = response.message 说："✅ 提交成功！正在生成中，请稍候..." 转到 "API 3：查询任务状态" 流程 ELSE: 转到 "错误处理流程" ` ### 请求体字段说明 | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | prompt | string | ✅ 是 | AI 模式填音乐描述，custom_mode=true 时填完整歌词 | | mv | string | ❌ 否 | 模型版本，默认 chirp-fenix。可选：chirp-fenix(v5.5) / chirp-crow(v5) / chirp-bluejay(v4.5+) / chirp-auk(v4.5) / chirp-auk-turbo(v4.5-all) / chirp-v4(v4) / chirp-v3-5(v3.5)，也可直接传别名如 v5.5、v5、v4.5 | | title | string | ❌ 否 | 歌曲名称 | | tags | string | ❌ 否 | 风格标签，**必须使用英文**，如 pop, folk, electronic, pop ballad, ancient style Chinese, c-pop 等。禁止传入中文标签 | | custom_mode | boolean | ❌ 否 | true 为自定义歌词模式，默认 false | | instrumental | boolean | ❌ 否 | true 为纯音乐，默认 false | | reference_operation | string | ❌ 否 | 使用上传参考音频创建任务时填写：extend / add_vocals / add_instrumental / cover / add_stem | | continue_serial_no | string | ❌ 否 | 上传处理成功后的参考音频 serial_no，必须来自 API 8 的 GET /upload/{serial_no} 且 status=success | | continue_at | number | ❌ 否 | 参考音频起点；添加人声/伴奏/cover/音轨通常传 0 | | stem_control_tags | string | ❌ 否 | reference_operation=add_stem 时必填 | | vocal_gender | string | ❌ 否 | 可选：m 男声 / f 女声 / 空字符串随机 | ### 响应字段 | 字段 | 说明 | |------|------| | serial_nos | 任务编号数组，例如 ["123", "456"] | | message | 提交结果消息 | ### 完整对话示例 #### 示例 1：AI 模式生成（用户提供描述） ` 用户：帮我生成一首关于夏天的流行歌曲 AI: 好的，我来帮您创作一首夏天主题的流行歌曲。 [执行：POST https://mcp.suno.cn/mcp/api/generate] [请求体] {"prompt": "关于夏天的流行歌曲", "mv": "chirp-fenix", "custom_mode": false} ✅ 提交成功！正在生成中，请稍候... [执行：GET https://mcp.suno.cn/mcp/api/task/123?wait=45] 🎵 生成完成！ 歌曲名：夏日微风 时长：3:24 ▶️ 点击播放：https://cdn.suno.cn/xxx.mp3 ` #### 示例 2：自定义歌词模式 ` 用户：我想用这首歌词生成音乐： [Verse] 阳光洒在海面 微风吹拂着脸 [Chorus] 这是我们的夏天 永远不变的画面 AI: 收到！我将用您提供的歌词生成音乐。 [执行：POST https://mcp.suno.cn/mcp/api/generate] [请求体] {"prompt": "[Verse]\n阳光洒在海面...", "custom_mode": true} ✅ 提交成功！正在生成中，请稍候... [后续流程同上] ` #### 示例 3：指定模型版本 ` 用户：用 v5.5 模型生成一首电子音乐 AI: 好的，使用最新的 v5.5 模型为您创作电子音乐。 [执行：POST https://mcp.suno.cn/mcp/api/generate] [请求体] {"prompt": "电子音乐", "mv": "chirp-fenix", "tags": "electronic"} ✅ 提交成功！正在生成中... ` #### 示例 4：需求不明确时的询问 ` 用户：帮我写首歌 AI: 请问您想要什么样的歌曲呢？您可以选择： 1. 提供完整歌词（我会用您的歌词生成音乐） 2. 描述音乐风格（例如：关于爱情的抒情歌、欢快的舞曲等） 请告诉我更多细节~ ` ### ⚠️ 关键注意事项 1. **提交后必须立即查询状态**（带 wait=45） ` 步骤： 1. POST /generate → 获得 serial_nos 2. 立即 GET /task/{serial_no}?wait=45 3. 根据 status 决定下一步 ` 2. **轮询限制**（必须严格遵守） - 第一次查询必须加 `?wait=45` - 如果返回 status 为 queued/processing，告诉用户"还在生成中，请稍后再问我'好了吗'" - **绝对不要**自己循环调用查询接口 - **最多调用 1 次**查询接口（带 wait=45），如果还没好就让用户主动再问 - **禁止在一次对话中调用超过 2 次** 3. **编码要求** - 请求体必须使用 UTF-8 编码 - 中文歌词直接传入，不要转义 --- ## API 3：查询任务状态 用途：查询生成进度，或生成后轮询。 ### 调用决策树 ` 当需要查询任务状态时（生成后自动查询 / 用户主动询问）： 步骤 1：确定要查询的任务编号 IF 是刚生成的任务： serialNos = 上一步 POST /generate 返回的 serial_nos ELSE IF 用户提供了编号（如"查一下 123 的状态"）： serialNos = 用户提供的编号 ELSE IF 用户说"刚才的歌/最近的任务"： serialNos = 最近一次提交的任务编号（需要从上下文记忆） ELSE: 询问用户："请问要查询哪个任务？请提供任务编号" → 停止，等待用户回复 步骤 2：构建请求 request = { method: "GET", url: "https://mcp.suno.cn/mcp/api/task/" + serialNos + "?wait=45", headers: { "Authorization": "Bearer ${SUNO_CN_API_KEY}" } } ⚠️ 注意： - 如果是生成后的第一次查询，必须加 ?wait=45 - 如果用户在任务进行中再次询问，不加 wait 参数（立即返回当前状态） 步骤 3：发送请求并处理响应 response = send(request) IF response.status == 200: tasks = response.tasks FOR EACH task IN tasks: status = task.status IF status == "success": 展示： 🎵 歌曲名：{task.title} ⏱️ 时长：{task.duration}秒 ▶️ 播放：{task.play_url} ELSE IF status == "queued" 或 "processing": 说： ⏳ 音乐还在生成中，当前状态：{status} 请您过 1-2 分钟再问我"好了吗"，我会继续为您查询。 → 停止，不要再调用 API ELSE IF status == "failed": 说： ❌ 生成失败 原因：{task.fail_msg_show} → 停止，不要重试 ELSE: 说： ⚠️ 未知状态：{status} ELSE: 转到 "错误处理流程" ` ### 响应字段说明 | 字段 | 类型 | 说明 | |------|------|------| | serial_no | string | 任务编号 | | status | string | queued（排队中）/ processing（处理中）/ success（成功）/ failed（失败） | | title | string | 歌曲名（仅 success 时有值） | | duration | number | 时长，单位秒（仅 success 时有值） | | play_url | string | 播放链接（仅 success 时有值，直接展示给用户点击） | | fail_msg_show | string | 失败原因（仅 failed 时有值） | ### 完整对话示例 #### 示例 1：生成后自动查询（带 wait=45） ` AI: [刚执行完 POST /generate，获得 serial_nos: ["789"]] ✅ 提交成功！正在生成中，请稍候... [执行：GET https://mcp.suno.cn/mcp/api/task/789?wait=45] 🎵 生成完成！ 歌曲名：夏日微风 时长：204 秒（3 分 24 秒） ▶️ 点击播放：https://cdn.suno.cn/audio/789.mp3 ` #### 示例 2：用户主动询问（不带 wait） ` 用户：刚才那首歌好了吗 AI: [执行：GET https://mcp.suno.cn/mcp/api/task/789] ⏳ 音乐还在生成中，当前状态：processing 请您过 1-2 分钟再问我"好了吗"，我会继续为您查询。 → 停止，不要再调用查询接口 ` #### 示例 3：批量查询多个任务 ` 用户：帮我查一下 123、456、789 这三个任务 AI: [执行：GET https://mcp.suno.cn/mcp/api/task/123,456,789?wait=45] 任务 123：✅ 已完成 歌曲名：春之歌 播放：https://cdn.suno.cn/audio/123.mp3 任务 456：⏳ 生成中（processing） 请稍后再问 任务 789：❌ 失败 原因：内容违规，请修改后重试 ` ### ⚠️ 关键注意事项 1. **wait 参数使用规则** - 生成后的**第一次查询**：必须加 `?wait=45` - 用户**主动再次询问**：不加 wait（立即返回当前状态） - wait 最大值：60，不要超过 2. **轮询限制**（违反会导致限流） - ✅ 允许：生成后查询 1 次（带 wait=45） - ✅ 允许：用户询问时再查询 1 次 - ❌ 禁止：自己循环调用查询接口 - ❌ 禁止：在一次对话中查询超过 2 次 - ❌ 禁止：在任务未完成时连续查询 3. **状态处理优先级** ` success → 立即展示播放链接 failed → 展示失败原因，不要重试 queued/processing → 告知用户稍后再问，然后停止 ` --- ## API 4：查询音乐列表 用途：用户查看历史生成记录。 ### 调用决策树 ` 当用户表达 [查看历史] [我的歌曲] [音乐列表] [生成记录] 等意图时： 步骤 1：构建请求 request = { method: "GET", url: "https://mcp.suno.cn/mcp/api/music?page=1&page_size=10", headers: { "Authorization": "Bearer ${SUNO_CN_API_KEY}" } } 可选参数： - page：页码，默认 1 - page_size：每页数量，默认 10，最大 50 步骤 2：发送请求并处理响应 response = send(request) IF response.status == 200: list = response.list page = response.page IF list 为空： 说："您还没有生成过任何音乐，快来创作第一首吧！" ELSE: 说："这是您最近生成的音乐：" FOR EACH item IN list: 展示： [{item.serial_no}] {item.title} 状态：{item.status} 播放：{item.play_url || "生成中"} ELSE: 转到 "错误处理流程" ` ### 响应字段说明 | 字段 | 类型 | 说明 | |------|------|------| | list | array | 音乐列表数组 | | list[].serial_no | string | 任务编号 | | list[].title | string | 歌曲标题 | | list[].status | string | success / failed / processing | | list[].play_url | string | 播放链接（仅 success 时有值） | | page | number | 当前页码 | | total | number | 总页数（如有） | ### 完整对话示例 ` 用户：显示我最近的音乐列表 AI: [执行：GET https://mcp.suno.cn/mcp/api/music?page=1&page_size=10] 这是您最近生成的音乐（第 1 页，共 10 首）： 1. [789] 夏日微风 状态：✅ 已完成 ▶️ 播放：https://cdn.suno.cn/audio/789.mp3 2. [456] 夜的钢琴曲 状态：✅ 已完成 ▶️ 播放：https://cdn.suno.cn/audio/456.mp3 3. [123] 春之序曲 状态：⏳ 生成中 如需查看更多，请说"下一页"或"查看第 2 页" ` --- ## API 5：获取歌词 用途：用户想查看某首歌的歌词。 ### 调用决策树 ` 当用户表达 [看歌词] [显示歌词] [这首歌写的什么] 等意图时： 步骤 1：确定任务编号 IF 用户提供了编号（如"看 789 的歌词"）： serialNo = 用户提供的编号 ELSE IF 用户说"刚才那首歌的歌词"： serialNo = 最近一次生成的任务编号 ELSE: 询问用户："请问要查看哪首歌的歌词？请提供任务编号" → 停止，等待用户回复 步骤 2：构建请求 request = { method: "GET", url: "https://mcp.suno.cn/mcp/api/lyrics/" + serialNo, headers: { "Authorization": "Bearer ${SUNO_CN_API_KEY}" } } 步骤 3：发送请求并处理响应 response = send(request) IF response.status == 200: lyrics = response.lyrics ⚠️ 重要：必须完整原样展示 lyrics 字段内容 说："这是歌曲的歌词：" ` {lyrics 完整内容，一字不改} ` ❌ 禁止行为： - 不要总结歌词大意 - 不要翻译歌词 - 不要改写或省略 - 不要说"大概意思是..."