suno-music

Name: suno-music
Author: acedatacloud

github.com/acedatacloud创意与媒体17274 次安装今天更新

代码仓库

关于 suno-music

通过 AceDataCloud 的 Suno API 生成和编辑音乐的技能，面向编码 Agent 和 OpenClaw 用户。涵盖提示词生成、自定义歌曲、音频处理及异步任务查询。

主要功能

01根据文本提示生成歌曲
02设置自定义歌词、标题和风格
03扩展、翻唱和混音现有音频
04生成歌词并优化风格描述
05管理自定义模型和录音室项目
06查询异步生成任务

适用场景

01根据简短描述创作歌曲
02使用提供的歌词和风格生成音乐
03扩展曲目或制作翻唱
04编辑多轨项目并渲染混音

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/acedatacloud/skills --skill suno-music

安装后在 Claude Code 中输入/suno-music确认已加载。

附带文件README.mdreadme.zh-CN.md

详细介绍

Ace Data Cloud 的 Suno

通过 AceDataCloud 的 Suno API 生成 AI 音乐。

从 skills.sh 安装并连接

此集成由 Ace Data Cloud 维护；它不是 Suno 官方发布的条目。只安装此 Skill：npx skills add acedatacloud/skills --skill suno-music --yes，或使用 skills.sh 公共页面。选择时请保留 slug suno-music。

阅读图文首次运行指南（简体中文），了解注册、Applications → General application、API 密钥访问与价格查询，以及编码 Agent 的环境变量位置。对于 skills.sh 安装，请使用本指南；任何特定于 ClawHub 的设置仅适用于 OpenClaw。此处链接的共享参考资料位于线上，因为精简安装不包含同级的 _shared/ 文件夹。

ClawHub / OpenClaw 设置

已从 skills.sh 安装？请从第 2 步继续。对于编码 Agent，请使用 npx skills add acedatacloud/skills --skill suno-music --yes 安装（安装与首次运行）。对于 OpenClaw，请使用 clawhub install @acedatacloud/suno，并确认 ClawHub 发布者是 @acedatacloud。
登录 AceDataCloud → Applications，打开 General application，并检查 Suno 访问权限、余额和当前价格。复制其 API 密钥，或选择 Manage Keys → Create 创建单独的密钥。复制密钥值时不要带上 Bearer ；platform-... 管理令牌不是服务 API 密钥。
如果启用 Allowed APIs 限制，请包含 /suno/audios 和 /suno/tasks。下方的高级工作流可能会调用其他路由。
对于编码 Agent 或直接命令，请在运行此 Skill 的进程环境中导出 ACEDATACLOUD_API_TOKEN="your_api_key_here"；项目 .env 文件的加载方式因 Agent 而异。对于 OpenClaw，请在 Gateway 主机的 ~/.openclaw/.env 中设置 ACEDATACLOUD_API_TOKEN=your_api_key_here，然后重启 Gateway 并开始新会话。切勿将密钥放入提示词或提交 .env 文件。
运行下方的 Quick Start。如果返回了任务 ID，请查询同一任务直至完成；不要为了检查进度而重复提交计费生成任务。

密钥设置、首次运行与故障排除图文指南 · 令牌详情

如果你从 skills.sh 进入，请使用适用于首次运行的 Applications。生成音乐前请查看当前价格。

快速开始

curl -X POST https://api.acedata.cloud/suno/audios \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a happy pop song about coding", "model": "chirp-v6", "async": true}'

异步： 所有生成任务均为异步。请参阅异步任务轮询。每隔 3-5 秒通过 POST /suno/tasks 传入 {"id": "<task_id>"} 进行轮询。

可用模型

模型	最适合
`chirp-v6`	当前的 v6 模型
`chirp-v6-wild`	v6 Wild 模型
`chirp-v6-mini`	v6 Mini 模型
`chirp-v5-5`	保留用于兼容的旧模型名称
`chirp-v5`	高品质
`chirp-v4-5-plus`	增强版 v4.5
`chirp-v4-5`	品质与速度的良好平衡
`chirp-v4`	快速、可靠
`chirp-v3-5`	旧版，稳定
`chirp-v3-0`	旧版

核心工作流

1. 快速生成（灵感模式）

根据文本描述生成歌曲。Suno 会自动创作歌词、风格和音乐。

POST /suno/audios
{
  "prompt": "an upbeat electronic track about the future of AI",
  "model": "chirp-v6",
  "instrumental": false
}

2. 自定义生成（完全掌控）

提供自己的歌词、标题和风格，实现精准控制。

POST /suno/audios
{
  "custom": true,
  "lyric": "[Verse]\nCode is poetry in motion\n[Chorus]\nWe build the future tonight",
  "title": "Digital Dreams",
  "style": "Synthwave, Electronic, Dreamy",
  "model": "chirp-v6",
  "vocal_gender": "f"
}

3. 延长歌曲

从指定时间戳开始续写现有歌曲，并添加新歌词。

POST /suno/audios
{
  "action": "extend",
  "audio_id": "existing-audio-id",
  "lyric": "[Bridge]\nNew section lyrics here",
  "continue_at": 120.0,
  "style": "Same style as original"
}

4. 翻唱 / 混音

以不同风格为现有歌曲创作新版本。

POST /suno/audios
{
  "action": "cover",
  "audio_id": "existing-audio-id",
  "style": "Jazz, Acoustic, Mellow"
}

5. 完整歌曲创作工作流

为获得最佳效果，请遵循以下多步工作流：

生成歌词 — 使用主题 / 提示词调用 POST /suno/lyrics
优化风格 — 调用 POST /suno/style 来完善风格描述
生成音乐 — 使用自定义操作、歌词和风格调用 POST /suno/audios
轮询任务 — 使用 id（批量任务则使用 ids）调用 POST /suno/tasks，直到状态为完成
可选：扩展 — 使用扩展操作添加更多段落
可选：拼接 — 使用拼接操作合并扩展后的片段
可选：转换 — 获取 MP3（/suno/mp3）、WAV（/suno/wav）、MIDI（/suno/midi）或 MP4（/suno/mp4）

可用操作

操作	描述
`generate`	根据提示词生成（默认）
`extend`	从指定时间戳继续现有音频
`upload_extend`	上传外部音频，然后扩展
`upload_cover`	上传外部音频，然后创作翻唱
`concat`	将扩展后的片段拼接为一首曲目
`cover`	复制现有音频的风格
`artist_consistency`	以自定义歌手的风格生成
`artist_consistency_vox`	侧重人声的歌手风格一致性
`stems`	将曲目分离为多个音轨
`all_stems`	分离为所有可用音轨
`replace_section`	替换歌曲中的特定时间段
`underpainting`	为上传的歌曲添加伴奏
`overpainting`	为上传的歌曲添加人声
`remaster`	对现有音频进行母带重制
`mashup`	混合多个音频 ID
`samples`	为上传的歌曲添加采样
`inspo`	创作一首受现有音频启发的歌曲

自定义音乐模型（测试版）

自定义模型可从 6–24 个已获授权的音频文件中学习可复用的音乐特征。创建模型需要付费，且耗时较长。提交前，请让用户确认文件和费用。

创建

POST /suno/custom-models
{
  "action": "create",
  "name": "My Album Sound",
  "audio_urls": [
    "https://cdn.example.com/track-01.mp3",
    "https://cdn.example.com/track-02.mp3",
    "https://cdn.example.com/track-03.mp3",
    "https://cdn.example.com/track-04.mp3",
    "https://cdn.example.com/track-05.mp3",
    "https://cdn.example.com/track-06.mp3"
  ]
}

发送稳定的 Idempotency-Key 标头，并在网络故障后重复使用该标头。保存返回的 id；持续查询，直到 status 为 ready。

查询和列出

POST /suno/custom-models
{"action": "retrieve", "id": "<custom-model-id>"}

POST /suno/custom-models
{"action": "retrieve_batch", "status": "ready", "limit": 20, "offset": 0}

生成

POST /suno/custom-models
{
  "action": "generate",
  "id": "<ready-custom-model-id>",
  "lyric": "[Verse]\nOriginal lyrics here",
  "style": "warm indie pop",
  "title": "New Song",
  "async": true
}

异步受理并不代表最终成功：请轮询返回的任务并检查 response.success。自定义模型请求不会回退到其他模型。模型必须属于当前 Suno 应用，且状态为 status: "ready"。

归档

POST /suno/custom-models
{"action": "delete", "id": "<custom-model-id>"}

delete 会归档平台资源，并阻止其后续使用。capacity_released: false 表示不保证已释放模型容量。

Studio Projects（测试版）

使用 POST /suno/projects 进行带版本管理的多轨编辑，而不是使用 /suno/audios。仅处理用户有权使用的音频。除 retrieve 外，每个操作都要发送 Idempotency-Key 标头（1–128 个字符）；恢复不确定的请求时，使用相同的密钥和负载。新操作需要使用新密钥；使用同一密钥发送不同负载会返回 409。

创建、检索和保存

POST /suno/projects
{"action":"create","title":"My Studio Project"}

保存 data.id，然后在编辑前使用该项目的 id 执行 retrieve。返回的 state 是权威数据；应修改它，而不是自行创建音轨／片段结构。空项目的初始内容为 {"tracks":[],"timing":{"bps":2}}。

POST /suno/projects
{"action":"retrieve","id":"PROJECT_ID"}

POST /suno/projects
{"action":"save","id":"PROJECT_ID","state":{"tracks":[],"timing":{"bps":2}}}

save 会替换完整状态，而非应用补丁：保留 retrieve.data.state 中的未知字段。即使结果包含 task_id，它也会同步完成。只有新建且未版本化的项目首次保存时，才可以省略 version_id。此后，每次修改、候选项生成和渲染都必须包含最新的 version_id。执行 save、add_track、commit_candidate 或 remove_track 后，应保留结果中的新版本号。upload、render、generate_track 和 replace_section 不会更改项目版本。遇到 HTTP 409 时，检索当前项目、协调变更，并使用新键提交；不要盲目重放过期编辑。

timing.bps 表示每秒节拍数，必须为正数，默认值为 2（120 BPM）。片段的 startBeats、endBeats 和 readStartBeats 是项目节拍，而不是音频分析中的小节位置。请求中的放置字段 start_beats／end_beats 是非负的项目节拍；start_seconds／end_seconds 用于选择源音频的秒数。

上传并添加音频

POST /suno/projects
{"action":"upload","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","audio_url":"https://cdn.example.com/reference.mp3","async":true}

轮询上传任务直至成功，然后读取 response.data.candidate.audio_id 并在 add_track 中使用：

POST /suno/projects
{"action":"add_track","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","audio_id":"AUDIO_ID","name":"Backing Vocals"}

默认放置方式会保持播放速度，并使用 timing.bps 将音频时长换算为节拍。

生成、选择并提交候选版本

项目仅接受以下公开模型名称：chirp-v3-5、chirp-v4、chirp-v4-5、chirp-v4-5-plus、chirp-v5、chirp-v5-5、chirp-v6、chirp-v6-wild、chirp-v6-mini。不受支持的名称会在提交前返回 400；接受名称并不保证所选操作能够成功。切勿静默切换模型。

POST /suno/projects
{"action":"replace_section","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","source_audio_id":"AUDIO_ID","start_seconds":35.12,"end_seconds":48.76,"model":"chirp-v6","replacement_lyrics":"New section lyrics","async":true}

replace_section 会返回两个候选版本，不会自动选择其中之一。结束位置不得超过源音频的实际时长。prompt 提供源歌词／上下文；replacement_lyrics 提供新片段的歌词。如果 fixed=true，范围必须短于 26 秒；此模式是否受支持取决于模型，且未在文档所述的 Backend 运行中验证。

要创建新音轨，先将源音频添加到项目，然后获取完整状态，并追加一条空音频音轨，其中包含全新的唯一 id、type:"audio"、clips:[]、takeLanes:[]、mute:false、solo:false、amplitude:1、instrument:{"type":"song"} 和 color:"#7251F7"。生成前保存完整状态，并保留新版本号和目标音轨 ID。将该版本渲染至成功状态，并使用 response.data.audio_id 作为混音参考：

POST /suno/projects
{"action":"generate_track","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","source_audio_id":"AUDIO_ID","render_audio_id":"RENDER_AUDIO_ID","model":"chirp-v5","start_seconds":12,"end_seconds":20,"stem_control_tags":"add Piano","tags":"gentle piano, instrumental","instrumental":true,"vocal_gender":"unspecified","async":true}

generate_track 始终会提交两个候选版本；不要发送 batch_size。stem_control_tags 是描述性文本，而非枚举值。instrumental 默认为 true；新音轨的文本／歌词使用 prompt，偏好使用 vocal_gender（f、m、unspecified，默认为 unspecified），但无法保证生成结果符合偏好。两种生成操作均接受 tags 和 negative_tags（默认为空字符串）。源音频的秒数范围不保证输出时长；请检查每个候选版本的实际时长。生成操作不会将候选版本添加到项目中。

轮询至成功状态，读取 response.data.operation_id 和所选的 response.data.candidates[].id（不要替换为项目 ID 或提交任务 ID），并让用户在提交前选择一个候选版本：

POST /suno/projects
{"action":"commit_candidate","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","operation_id":"OPERATION_ID","candidate_id":"CANDIDATE_ID","track_id":"TRACK_ID","async":true}

候选版本与生成时使用的版本绑定。生成新音轨候选版本前，先保存空目标音轨；之后再创建会导致候选版本过期。
替换候选版本必须放回包含唯一源片段的原音轨。完整接管会保留其位置；片段替换会保留周围的片段。对于这些替换操作，不要提供 start_beats / end_beats。如果无法可靠匹配时长，请求会返回 400，且项目不会发生变化。
新音轨候选版本使用已保存的空音轨，默认从源片段的起始位置开始，也可以指定不重叠的范围。目标音轨中若有重叠，请求会返回 400。
移除音轨前，请确认目标音轨，然后提交当前版本并再次获取状态，以验证剩余内容：

POST /suno/projects
{"action":"remove_track","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","track_id":"TRACK_ID"}

渲染和恢复

POST /suno/projects
{"action":"render","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","title":"Final Mix","async":true}

省略 start_beats / end_beats，即可从最早的可听片段起点渲染到最晚的可听终点。静音的轨道/片段会被排除；如果存在独奏轨道，则只处理这些轨道。空项目或不可听的项目、负边界，或结束位置不大于起始位置，都会返回 400。任务最终成功后，保存返回的 render_id、audio_id、audio_url 和时长。

upload、add_track、generate_track、replace_section、commit_candidate 和 render 始终异步运行，即使设置了 async:false 也一样。对于每个异步 Projects 操作，每隔 3–5 秒使用 {"action":"retrieve","id":"TASK_ID"} 轮询 POST /suno/tasks。只有出现 finished_at 且 response.success=true 才表示成功；response.success=false 表示失败。失败时读取 response.error，即使是在收到回调之后。HTTP 200 或 task_id 表示已受理，不代表音频已完成。Projects 的这项规则与下文的 /suno/audios 片段状态规则不同。

候选项 URL 可读取或提交成功，并不能证明项目可以渲染。文档中的 Backend 运行生成并提交了一条新轨道，但使用该轨道渲染失败，返回 studio_audio_unavailable；替换候选项也未能提交，因为其时长既不匹配源音频，也不匹配所选区间。保留原始项目和候选项以供检查；不要猜测放置位置，也不要自动重复付费生成。移除不可用轨道之前，先向用户确认预期编辑，获取当前状态，只移除该轨道，然后重新获取状态并渲染新版本，以验证是否恢复。Projects 和候选项绑定到其应用及执行环境；不要假设它们可跨应用复用或能自动故障转移。

相同的键和负载会重放原始结果（包括失败），而不会再次生成。若要明确重试，先确认原任务已失败，然后使用新键。原任务仍在处理中或状态不确定时，切勿重新提交。保留 trace_id 以便排查问题；遇到 studio_state_invalid (400)、studio_model_unsupported (400)、studio_unavailable / studio_model_unavailable (503)、too_many_requests (429) 和 studio_audio_unavailable / content_rejected (403) 时，应报告这些错误，而不是更换模型或丢弃编辑内容。

辅助端点

端点	方法	用途
`/suno/lyrics`	POST	根据提示词生成结构化歌词（`model`：`"default"` 或 `"remi-v1"`）
`/suno/style`	POST	优化/润色风格描述
`/suno/mashup-lyrics`	POST	合并两组歌词
`/suno/mp4`	POST	获取歌曲的 MP4 视频版本
`/suno/wav`	POST	转换为无损 WAV 格式
`/suno/midi`	POST	提取 MIDI 数据，以便在 DAW 中编辑
`/suno/vox`	POST	提取人声轨道（分离音轨）
`/suno/voices`	POST	根据音频 URL 创建可复用的声音；必需参数为 `audio_url`，可选参数为 `name` 和 `description`
`/suno/timing`	POST	获取逐词时间信息/字幕
`/suno/persona`	POST	将人声风格保存为可复用的 persona；必需参数为 `audio_id` 和 `name`
`/suno/persona`	GET	列出可复用的 persona
`/suno/persona`	DELETE	删除可复用的 persona
`/suno/upload`	POST	上传外部音频，以便扩展/翻唱
`/suno/tasks`	POST	查询任务状态和结果
`/suno/custom-models`	POST	创建、使用自定义音乐模型生成内容、查询、列出或归档模型
`/suno/projects`	POST	创建、获取、编辑、生成候选项，并渲染有版本记录的 Studio 项目（Beta）

高级参数

参数	类型	描述
`lyric_prompt`	object	用于自动生成歌词的结构化提示词载荷（在 `custom: true` 且未明确提供 `lyric` 时使用）
`negative_tags`	string	要避免的风格或流派标签（例如 `"heavy metal, distortion"`）；仅在 `custom: true` 时生效。此端点目前没有强制固定的字符数限制；请保持简洁，因为输入过长仍可能失败
`style_influence`	number	风格影响强度（高级自定义模式，仅 v5+ 支持）
`audio_weight`	number	翻唱时音频参考的权重（高级功能，仅 v5+ 支持）
`duration`	integer	目标曲目时长（秒，通常为 10–360）。较新的模型（如 `chirp-v5-5`）在 `generate` 搭配 `custom: true` 时支持最佳

歌词格式

使用方括号中的段落标记：

[Verse 1]
Your verse lyrics here

[Chorus]
Catchy chorus lyrics

[Bridge]
Bridge section

[Outro]
Ending lyrics

音频处理失败恢复

可下载的音频文件并不保证其 audio_id 仍可用于后续处理，例如翻唱、延长或分离音轨。请保留原始音频和任务凭证；不要根据下载 URL 推断是否可进行处理。

对于 /suno/audios，请保留以下公开的 HTTP 500 错误代码，而不要报告笼统的失败：

代码	含义
`suno_processing_unavailable`	音乐处理不可用
`suno_model_unavailable`	所选模型不支持此操作
`suno_processing_failed`	音乐处理未返回音频

如果 /suno/audios 返回 HTTP 500 错误 api_error，且消息为 the account may have been offline，也请保留此错误。

出现上述任一错误时，如果返回了 task_id 和 trace_id，请保留这些 ID，并使用它们联系支持人员，切勿提供 API 密钥。如果提交状态不确定，请先查询现有任务，再考虑发起其他请求。不要自动重试付费操作，也不要悄悄切换模型；结果失败并不代表可以发起新的计费请求。

注意事项

/suno/audios 生成是异步的——设置 "callback_url" 可立即获取任务 ID，然后使用 {"id":"<task_id>"} 或 {"ids":[...],"action":"retrieve_batch"} 轮询 /suno/tasks
**/suno/audios 的关键事项：**检查片段的 state 字段——只有 state: "complete" 且 success: true 才表示完成。在 pending 期间，API 可能会返回中间的 audio_url 值（流式预览）。不要仅因为 audio_url 非空就停止轮询
歌词最多约 3000 个字符。较长的歌曲请使用延长工作流
风格标签是描述性短语，而非枚举值（例如，“Synthwave, Electronic, Dreamy”）
vocal_gender（"f"/"m"）仅受 v4.5+ 模型支持
variation_category（"high"/"normal"/"subtle"）仅受 v5+ 模型支持
duration 会按你发送的值转发——支持情况因模型和操作而异，不支持的组合可能会被忽略或返回错误，因此批量处理前请先通过一次请求进行验证。请注意，请求中的 duration 是目标时长；每个返回片段中的 duration 是实际时长，可能略有差异
concat 操作会合并延长后的歌曲片段——需要延长后曲目的 audio_id
persona 需要一个现有的 audio_id 和一个 name；可选的 vox_audio_id、vocal_start、vocal_end 和 description 可进一步完善人声参考
使用外部音频进行延长或翻唱前，请通过 /suno/upload 上传

MCP：pip install mcp-suno | 托管地址：https://suno.mcp.acedata.cloud/mcp | 查看所有 MCP 服务

支持 Markdown

登录后评论

基本信息

作者: acedatacloud
仓库: acedatacloud/skills
分类: 创意与媒体
安装次数: 274
GitHub Stars: 17

报告问题