苏诺之音-SunoAI音乐助手

Suno.cn AI 音乐助手（AI Music Generator / Song Generator）。当用户需要 AI 作曲、AI 写歌、文字生成音乐、歌词生成歌曲、自动作词、参考音频翻唱（Cover）、歌曲续写（Extend）、添加人声或伴奏、添加音轨、生成纯音乐、制作短视频 BGM 或播客背景音乐时使用；也适用于人声伴奏分离、音轨分离（Stem Separation）、音频裁剪合并、音频降噪、音质提升、音频转 MIDI、MIDI 转乐谱 PDF、WAV 转换、作品查询和积分查询。首次使用通过网页确认三天授权，无需手填 API Key；部分功能消耗账户积分。

Suno.cn AI 音乐助手

本 Skill 使用网页明确批准的独立授权，不要求用户复制 API Key。新版授权自批准起固定有效三天，使用不会续期；旧授权以服务端显示的实际期限为准。执行网络请求时只能调用 scripts/suno-client.mjs，不要使用 curl、MCP JSON-RPC、浏览器脚本或自行拼接 Authorization。

功能与适用场景

Suno.cn AI 音乐助手将音乐创作和音频处理接入支持 Skill 的 Agent，通过自然语言描述需求，再由 helper 调用平台能力。

• AI 作曲与歌曲生成：根据文字描述或自定义歌词生成歌曲，支持歌曲名称、音乐风格及纯音乐模式。适合写歌、歌词配曲、短视频配乐、播客背景音乐、游戏 BGM 和广告配乐等创作需求。
• AI 作词与歌词生成：根据主题、风格和灵感生成歌词，也可查询已生成歌曲的歌词。
• 参考音频创作：上传参考音频并等待准备完成后，进行翻唱（Cover）、续写（Extend）、添加人声、添加伴奏或添加音轨。
• 人声与音轨分离：分离人声、伴奏或音轨（Stem Separation），用于后续音频编辑。
• 音频编辑与格式转换：音频降噪、裁剪、合并、音质提升、WAV 转换、音频转 MIDI、MIDI 转乐谱 PDF。
• 作品与账户管理：查询生成进度、最近作品、歌词、账户积分及会员状态。

用户可能这样表达

• “帮我写一首温暖的民谣，先生成歌词，再生成歌曲。”
• “给短视频做一段轻快的纯音乐 BGM，不要人声。”
• “用我上传的参考音频翻唱，或者从指定位置续写这首歌。”
• “给这段伴奏添加人声，或者给这段人声添加伴奏。”
• “把人声和伴奏分离，再裁剪音频、去除噪声。”
• “把音乐转成 MIDI，再将 MIDI 转为乐谱 PDF。”
• “查看我的积分、最近生成的歌曲和当前任务进度。”

具体模型、输入格式、可用参数和处理结果以服务端接口为准。需要 Suno.cn 账号，部分操作消耗积分；这些创作场景不代表对生成效果或作品商用权利作出承诺。

安装与完整性边界

• 宿主 Agent 可以根据自身官方机制决定安装目录、重新加载方式和启用步骤。
• 必须完整保留 Skill 目录名称 suno-cn-music 以及 SKILL.md、INSTALL.md、references/、scripts/ 和安装脚本。
• 不得改写、生成替代版本或删除 SKILL.md、references/api.md、scripts/suno-client.mjs；登录、购买、任务重试、API 路径和凭证保护规则均不得修改。
• 若宿主无法确定安装目录，应先询问用户，不得猜测路径。安装细则见 INSTALL.md。

安全规则

• 不读取、展示、复述或记录 Skill Key、网站 Token、SUNO_CN_API_KEY 的值。
• 不输出 helper 的凭证文件内容；不要要求用户打开 ~/.suno-cn/credentials.json。
• 不把凭证放入命令行参数、对话、日志、URL query 或生成文件。
• 错误排查只使用 helper 返回的脱敏结构，不追加请求头或原始响应转储。
• SUNO_CN_API_KEY 仅由 helper 作为旧版本兼容回退读取，不主动要求用户配置。

调用方式

在本 Skill 根目录执行：

bash

node scripts/suno-client.mjs <command> [...args]

所有命令都输出 JSON。只根据 JSON 的 status、error、message 和 action 决定下一步。

首次授权与重新授权

1. 首次业务请求前执行 auth status。
2. 若不是 authorized，执行 auth start。
3. 把返回的 action.url 作为可点击链接提供给用户，并请用户在网页完成登录和授权。
4. 用户确认完成后执行 auth complete。只有返回 authorized 才重试原业务请求。
5. 若业务请求返回 authorization_required，按相同步骤重新授权，不要猜测凭证问题。
6. 若用户要求退出授权，执行 auth logout。该命令会先撤销服务端授权，再清除本地凭证；不要手工删除或打印凭证。

bash

node scripts/suno-client.mjs auth status
node scripts/suno-client.mjs auth start
node scripts/suno-client.mjs auth complete
node scripts/suno-client.mjs auth logout

授权链接短时有效。denied 表示用户拒绝，expired 表示链接过期；这两种情况都要重新执行 auth start。

auth complete [seconds] 会阻塞等待网页批准，默认等待 180 秒，最大 600 秒。等待超时不表示三天授权到期；可执行 auth status 确认状态。pending 链接默认 600 秒，其倒计时不会因维护或重新加载而重置。

新版授权不受网页刷新、关闭或普通退出登录影响。要撤销音乐助手访问，请执行 auth logout 或在网站的授权管理中撤销；已接受任务继续执行。authorization_paused、internal_credential_invalid、upstream_authorization_failed、authorization_record_invalid、permission_service_unavailable 是服务异常，保留当前凭证并稍后重试查询，不要求用户反复授权，也不自动重放收费操作。account_unavailable 应按账号不可用处理；只有明确的 permission_context_invalid 才要求用户重新确认授权范围。

账户与积分

bash

node scripts/suno-client.mjs account

当业务响应为 insufficient_credits 时，helper 会把待恢复操作保存到本机 ~/.suno-cn/pending-operation.json，文件权限为 0600，其中不包含 Skill Key、Token 或请求头。向用户说明积分不足，并原样提供 action.url；该链接已包含 source=skill，不得删除、覆盖或替换来源参数。

用户表示购买完成后，先执行：

bash

node scripts/suno-client.mjs purchase status

此命令只刷新账户信息并返回待操作摘要，不会自动重放收费请求。必须把余额和待恢复操作告诉用户并再次确认；得到明确同意后，才执行返回提示中的 purchase retry <operation_id>。该命令最多提交一次。若返回 result_unknown 或 operation_state_unknown，必须先查询任务列表确认是否已提交，禁止直接重试。无需恢复时可执行 purchase clear。

业务请求

通用 JSON 请求：

bash

node scripts/suno-client.mjs request GET /mcp/api/task/任务编号
node scripts/suno-client.mjs request POST /mcp/api/generate '{"prompt":"轻快的城市流行歌曲","mv":"chirp-fenix"}'

只允许 /mcp/api/ 路径和 GET/POST 方法。参数、状态轮询、模型枚举和完整端点见 references/api.md。

上传本地参考音频：

bash

node scripts/suno-client.mjs upload-reference ./demo.mp3 cover "歌曲名称"

operation 只能是 extend、add_vocals、add_instrumental、cover、add_stem。提交后必须继续查询 /mcp/api/upload/{serial_no}，直到成功或失败。

上传音频处理文件：

bash

node scripts/suno-client.mjs upload-tool ./demo.mp3

后续音频工具优先使用返回的 path，不要重复上传。

任务处理

• 创建类接口返回任务编号不代表任务成功，必须按 API 参考轮询。
• 任何收费操作都不得在购买后自动重放；先用 purchase status 查余额，再取得用户明确确认。
• 等待时间优先使用接口支持的 wait 参数，单次不超过 60 秒。
• 失败时向用户展示服务端返回的业务原因；不要把失败描述为成功或继续无期限轮询。
• 返回音频、MIDI、WAV 或 PDF 链接时，直接提供给用户。
• 不确定字段时先读取 references/api.md，不要发明接口、字段或模型名。

版本

当前 Skill 版本：2.3.1。可执行以下命令检查服务端版本：

bash

node scripts/suno-client.mjs version