SunoAI-MIDI转乐谱

概述

Suno.cn MIDI 转乐谱

使用随包提供的命令行 helper 将本地 MIDI 文件转换为乐谱 PDF。首次使用通过网页授权；转换任务的积分与可用性以服务端返回为准。

何时使用

适用于把本地 .mid 或 .midi 文件转换为乐谱 PDF。

不用于音频转 MIDI、歌曲转 MIDI、音频处理或编辑 MIDI 内容。用户有多个候选文件时，必须让用户明确选择，不猜测。

核心规则

1. 所有网络请求只能通过 node scripts/suno-client.mjs ... 发起。不得使用 curl、浏览器脚本、自行拼接 HTTP 请求或 MCP JSON-RPC。
2. 不读取、打印、复述或记录 Skill Key、网站 Token、SUNO_CN_API_KEY 或凭证文件内容。
3. 提交前按需读取 [MIDI 转乐谱契约](references/midi-to-sheet.md)，只使用已声明字段和约束。
4. 本地上传最大 100 MiB。上传工具支持多种格式，但本任务输入必须是 .mid 或 .midi，不接受 MP3、WAV、M4A 或 MP4。
5. 上传成功返回的 path 是转换输入；不要重复上传。带 wait=45 时服务端最多等待 60 秒；返回 submitted、排队或处理中时不得把乐谱 PDF 说成已生成。
6. 在用户明确要求执行前确认源 MIDI 文件。返回积分不足或结果未知时，严格执行共享 helper 的恢复流程，不得静默重试。

执行流程

1. 确认用户明确选择一个本地 MIDI 文件；多个候选时要求用户指定。
2. 首次业务请求前执行 auth status。未授权时执行 auth start，把返回的原始 action.url 同时作为可点击 Markdown 链接和可复制代码块交给用户，等待其确认网页授权完成后执行 auth complete。
3. 执行 upload-tool <file>，保存返回的 path。
4. 调用 POST /mcp/api/tool/midi-to-sheet?wait=45，请求体仅传上传返回的 path。
5. 返回完成结果时交付 result 中的乐谱 PDF 链接；返回 submitted、queued 或 processing 时说明仍在处理并保留任务编号供后续查询。

授权、积分与恢复

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 purchase status

• action.url 中的 code 是一次性授权请求定位码，不是 Skill Key、网站 Token 或密码。不得加密、哈希、脱敏、截断、二次编码、重组、替换或删除该链接；不得自行拼接链接。
• 授权完成前不提交上传或转换请求。用户要求撤销授权时执行 auth logout，不要手工删除凭证。
• 返回 insufficient_credits 时，原样交付 action.url。用户购买完成后先执行 purchase status，再次取得用户明确确认后才执行 helper 返回的 purchase retry <operation_id>；最多提交一次。
• 返回 result_unknown 或 operation_state_unknown 时，先查询转换任务，禁止直接重试。

常用命令

node scripts/suno-client.mjs upload-tool ./composition.mid
node scripts/suno-client.mjs request POST '/mcp/api/tool/midi-to-sheet?wait=45' '{"path":"上传返回的path"}'

完整字段、文件限制、状态和错误处理见 [MIDI 转乐谱契约](references/midi-to-sheet.md)。