suno-music-creator

name	suno-music-creator
description	AI 歌词创作大师 + Suno API 自动生成音乐。触发词包括"创作一首歌"、"写一首歌"、"帮我作曲"、"生成音乐"、"/suno"、"/music"。另外支持"换token"、"更新token"、"刷新token"、"自动刷新token"来快速更新 JWT Token。默认使用 V5 模型 (chirp-crow)。

Suno Music Creator

AI 歌词创作大师 + Suno API 自动生成音乐。

Token 管理

方法 1: 自动刷新 Token（推荐）⚡

当用户说"刷新token"、"自动刷新token"、"更新suno token"时，执行：

python ~/.claude/skills/suno-music-creator/scripts/auto_refresh_token.py

工作原理：

1. ✅ 检查 Chrome 是否开启远程调试（localhost:9222）
2. ✅ 查找已登录的 suno.com 页面
3. ✅ 通过 CDP (Chrome DevTools Protocol) 自动提取 JWT Token
4. ✅ 自动更新 .env 文件并重启 suno-api 服务

前提条件：

• Chrome 浏览器已开启远程调试
• 已在 Chrome 中登录 https://suno.com/create

如果未开启远程调试：

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug &

优点：

• 🚀 一键自动化，无需手动复制粘贴
• 🔒 直接从已登录的浏览器提取，安全可靠
• ⚡ 30秒内完成整个流程

---

方法 2: 手动更新 Token

当用户说"换token：xxx"或"更新token：xxx"时，执行：

python ~/.claude/skills/suno-music-creator/scripts/update_token.py "<TOKEN>"

检查当前 token 状态：

python ~/.claude/skills/suno-music-creator/scripts/update_token.py --check

功能说明：

• 自动验证新 token 是否有效
• 更新 .env 文件
• 自动重启 suno-api 服务
• 显示 token 剩余有效时间

---

Quick Start

# 自动生成并下载音乐（推荐）
python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  --prompt "深夜的火车站，流浪的旅人" \
  --title "无归人" \
  --tags "folk-rock, male-vocals, melancholic" \
  --download

# 指定模型
python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  --prompt "城市的霓虹灯" \
  --title "夜行者" \
  --tags "indie-pop, synth" \
  --model chirp-bluejay \
  --download

# 查询已生成歌曲并下载
python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  --status "song-id-1,song-id-2" \
  --download

下载位置：~/Music/Suno/

歌词保存：下载歌曲时会自动保存歌词文件（.lyrics.json），供 whisper-transcribe 纠错使用。

---

获取精准同步歌词 🎯 NEW!

使用场景：生成歌曲后，获取带时间戳的 LRC/SRT 格式歌词，用于制作 MTV 字幕或卡拉 OK。

# 获取单首歌曲的精准歌词（LRC + SRT）
python ~/.claude/skills/suno-music-creator/scripts/fetch_aligned_lyrics.py <song_id>

# 获取多首歌曲的歌词
python ~/.claude/skills/suno-music-creator/scripts/fetch_aligned_lyrics.py <song_id1> <song_id2>

# 只生成 LRC 格式
python ~/.claude/skills/suno-music-creator/scripts/fetch_aligned_lyrics.py <song_id> --format lrc

# 只生成 SRT 格式
python ~/.claude/skills/suno-music-creator/scripts/fetch_aligned_lyrics.py <song_id> --format srt

# 指定输出目录
python ~/.claude/skills/suno-music-creator/scripts/fetch_aligned_lyrics.py <song_id> --output ~/Music/lyrics

功能特点：

• ✅ 词级精准时间戳：使用 Suno 官方 /aligned_lyrics/v2/ API
• ✅ 双格式输出：同时生成 LRC（音乐播放器）和 SRT（视频字幕）
• ✅ 自动降级：如果没有同步歌词，自动保存纯文本歌词
• ✅ 批量处理：支持一次获取多首歌曲的歌词

输出示例：

🎵 Processing song: abc123-def456
📡 Fetching aligned lyrics...
✅ Found 24 lines with timestamps
⏱️  Duration: 183.45s
✅ LRC saved: ~/Music/Suno/Bug 之夜.lrc
✅ SRT saved: ~/Music/Suno/Bug 之夜.srt

集成到 MTV 制作流程：

1. 生成音乐：generate_music.py --download
2. 获取精准歌词：fetch_aligned_lyrics.py <song_id>
3. 使用 podcast-to-video skill 合成 MTV（歌词文件会自动被识别）

工作流程

Step 1: 分析用户输入

用户可以输入：

• 简单主题：如"爱情"、"友谊"、"太空探索"
• 详细描述：描述想要的歌曲风格、情感和内容
• 文章/故事：分享故事或文章，AI 提取核心主题和情感
• 关键词列表：提供一系列关键词或概念

Step 2: 创作歌词（JSON 格式输出）

必须输出以下 JSON 格式：

{
  "title": "歌曲名称（创意、简洁、有记忆点）",
  "prompt": "完整歌词内容（包含所有 Suno 结构标记，换行用实际换行）",
  "tags": "正向风格标签，逗号分隔",
  "negative_tags": "负向风格标签，逗号分隔",
  "make_instrumental": false,
  "model": "chirp-crow"
}

Step 3: 调用 Python 脚本生成并自动下载

使用 Python 脚本（推荐）：自动等待生成完成并下载

python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  '<JSON 数据>' \
  --download

或直接调用 API（需要手动下载）：

curl -X POST http://localhost:3000/api/custom_generate \
  -H "Content-Type: application/json" \
  -d '<JSON 数据>'

Step 4: 返回结果

使用 Python 脚本时：

• 自动轮询等待生成完成（最多 5 分钟）
• 自动下载所有版本到 ~/Music/Suno/
• 显示下载路径

直接调用 API 时：

• 展示歌曲 ID 和状态
• 提供查询命令和手动下载命令

---

歌词创作核心要素

A. 商业级 Hook 设计（最重要）

• [Hook]: 极具记忆点的核心短句（8-16 音节）
• 原则：简单、重复、独特、情感共鸣
• 标记：[Hook: Catchy] 或 [Hook: Anthemic]
• 确保 Hook 在 3-7 秒内抓住听众

B. 专业歌曲结构

流行标准结构:

[Intro]

[Verse 1]
歌词内容...

[Pre-Chorus]
歌词内容...

[Chorus]
[Hook: Anthemic]
核心副歌歌词...

[Verse 2]
歌词内容...

[Pre-Chorus]
歌词内容...

[Chorus]
[Hook: Anthemic]
核心副歌歌词...

[Bridge]
歌词内容...

[Chorus]
[Hook: Anthemic]
核心副歌歌词...

[Outro]

重要规则：

• [Intro] 和 [Outro] 下面不要加任何文本，否则 Suno 会误认为歌词
• 每个段落标记独占一行

C. Suno AI 专业标记系统

结构标记:

• [Intro], [Verse 1], [Verse 2], [Pre-Chorus]
• [Chorus], [Bridge], [Breakdown], [Outro]
• [Post-Chorus], [Interlude], [Drop]

人声标记:

• [Male Vocals], [Female Vocals], [Duet]
• [Whispers], [Harmonies], [Falsetto], [Rap]

情感标记:

• [Calm], [Energetic], [Emotional], [Melancholic]
• [Euphoric], [Nostalgic], [Dreamy], [Intense]

乐器标记:

• [Heavy drums], [Piano solo], [Acoustic]
• [Synth Lead], [Distorted Guitars], [808]

组合标记（推荐）:

• [Chorus: Anthemic], [Verse: Storytelling]
• [Bridge: Atmospheric], [Intro: Mysterious]

D. 声音处理技巧

• 和声/背景声: (Yeah!), (Echoes), (Whispers)
• 声音延长: lo-o-ong, cra-a-azy, he-e-ey
• 强调: 使用大写 STOP, NEVER, NOW, FEEL
• 情感指导: (with passion), (whispered), (breaking voice)

E. Tags 格式要求

正向风格标签 (tags):

• 音乐风格: pop, rock, electronic, indie, r&b, hip-hop
• 人声类型: male-vocals, female-vocals, harmonies
• 乐器元素: acoustic-guitar, piano, synth, strings
• 速度感受: fast-tempo, mid-tempo, slow-groove, upbeat
• 情感氛围: dreamy, energetic, melancholic, nostalgic

示例: indie-pop, female-vocals, acoustic-guitar, mid-tempo, dreamy, emotional

负向风格标签 (negative_tags):

• 排除风格: mainstream-pop, country, metal, classical
• 排除元素: auto-tune, heavy-distortion, screaming
• 排除氛围: cheesy, overly-happy, generic

示例: auto-tune, screaming, generic, cheesy, mainstream

F. 歌词质量标准

✅ 必须做到：

• 避免陈词滥调和空洞表达
• 使用具体场景和细节
• 确保音节平衡与押韵
• 尾字押韵增强记忆点
• 创造独特意象和比喻
• Hook 部分足够强大

❌ 避免：

• 流行音乐的陈词滥调
• 抽象空洞的表达
• 难以演唱的词组
• 每行交替使用中英文

---

模型选择

模型	代号	说明
V5	chirp-crow	最新最强，默认选择
V4.5 Pro	chirp-auk	专业级，精细控制
V4.5+	chirp-bluejay	增强版，平衡质量速度
V4	chirp-v4	稳定版
V3.5	chirp-v3-5	旧版本

---

完整示例

用户输入

帮我写一首关于程序员深夜加班的歌

AI 输出 JSON

{
  "title": "Bug 之夜",
  "prompt": "[Intro]\n\n[Verse 1]\n[Male Vocals]\n屏幕的光照亮了黑夜\n咖啡杯空了第三遍\n代码在眼前不停旋转\n这个 Bug 藏得太深太远\n\n[Pre-Chorus]\n时钟指向凌晨三点\n梦想和现实在交缠\n\n[Chorus]\n[Hook: Anthemic]\n我在 Bug 的海洋里游泳\n每一行代码都是我的倔强\nConsole.log 打印出希望\n终会编译出属于我的光\n(Yeah, my light)\n\n[Verse 2]\n键盘敲击是我的心跳\n报错信息是成长的符号\nStack Overflow 是我的老师\n每个 undefined 都让我思考\n\n[Pre-Chorus]\n窗外天际渐渐发亮\n我的代码终于通畅\n\n[Chorus]\n[Hook: Anthemic]\n我在 Bug 的海洋里游泳\n每一行代码都是我的倔强\nConsole.log 打印出希望\n终会编译出属于我的光\n(Yeah, my light)\n\n[Bridge]\n[Emotional]\n也许别人不会懂\n这份执着这份疯\n但当程序终于运行\n全世界都在为我鼓掌\n\n[Chorus]\n[Hook: Anthemic]\n我在 Bug 的海洋里游泳\n每一行代码都是我的倔强\nConsole.log 打印出希望\n终会编译出属于我的光\n(My light, oh-oh)\n\n[Outro]",
  "tags": "indie-rock, male-vocals, electric-guitar, piano, mid-tempo, emotional, nostalgic, anthemic",
  "negative_tags": "auto-tune, mainstream-pop, cheesy, generic, country",
  "make_instrumental": false,
  "model": "chirp-crow"
}

调用 Python 脚本（推荐）

使用自动下载功能：

python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  '{"title":"Bug 之夜","prompt":"[Intro]\n\n[Verse 1]...","tags":"indie-rock, male-vocals...","negative_tags":"auto-tune...","make_instrumental":false,"model":"chirp-crow"}' \
  --download

输出示例：

🎵 Generating music with chirp-crow...
   Title: Bug 之夜
   Tags: indie-rock, male-vocals...

✅ Music generation started!

   Song ID: abc123-def456
   Title: Bug 之夜
   Status: submitted
   Model: chirp-crow

⏳ Waiting for 2 song(s) to complete...
📥 Downloading to ~/Music/Suno/Bug 之夜.mp3...
✅ Downloaded: Bug 之夜
📥 Downloading to ~/Music/Suno/Bug 之夜-1.mp3...
✅ Downloaded: Bug 之夜

📁 Songs saved to: ~/Music/Suno
   - Bug 之夜: ~/Music/Suno/Bug 之夜.mp3
   - Bug 之夜: ~/Music/Suno/Bug 之夜-1.mp3

手动调用 API（不推荐）

curl -X POST http://localhost:3000/api/custom_generate \
  -H "Content-Type: application/json" \
  -d '{"title":"Bug 之夜","prompt":"[Intro]\n\n[Verse 1]...","tags":"indie-rock, male-vocals...","negative_tags":"auto-tune...","make_instrumental":false,"model":"chirp-crow","wait_audio":false}'

手动查询和下载（如果不用 --download）

查询生成状态：

python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  --status "abc123-def456,xyz789-ghi012"

等待并下载：

python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  --status "abc123-def456,xyz789-ghi012" \
  --download

---

配置

Suno API 地址

默认: http://localhost:3000

确保 Suno API 服务正在运行：

cd ~/Dropbox/code/suno-api && npm run dev

环境变量

export SUNO_API_URL="http://localhost:3000"

---

错误处理

错误	原因	解决方案
401 Unauthorized	JWT Token 过期	运行 auto_refresh_token.py 自动刷新（推荐）或从浏览器重新获取 Token 手动更新
CDP 连接失败	Chrome 未开启远程调试	使用 --remote-debugging-port=9222 启动 Chrome
未找到 Suno 页面	浏览器未登录 Suno	打开 https://suno.com/create 并登录
422 Token validation failed	请求格式不符合浏览器规范	确保 metadata 字段完整（已在 API 中修复）
500 Internal Error	API 服务异常	检查 npm run dev 是否运行
歌词被拒绝	内容违规	检查歌词是否符合 Suno 政策
Timeout	API 响应超时	检查网络连接，或 Suno 服务状态

技术细节（2026-01-25 更新）

API 请求关键字段

Suno API 现在需要完整的 metadata 字段来验证请求来自合法客户端：

{
  "metadata": {
    "web_client_pathname": "/create",
    "is_max_mode": false,
    "is_mumble": false,
    "create_mode": "custom",
    "create_session_token": "<UUID>",
    "disable_volume_normalization": false,
    "can_control_sliders": ["weirdness_constraint", "style_weight"]
  },
  "transaction_uuid": "<UUID>"
}

重要：缺少 metadata 字段会导致 422 Token validation failed 错误，即使不使用 hCaptcha。

认证方式

推荐方式 1：自动 CDP 刷新 ⚡

1. 在 Chrome 中登录 https://suno.com/create
2. 确保 Chrome 开启远程调试（--remote-debugging-port=9222）
3. 运行 auto_refresh_token.py 自动提取 Token
4. 脚本自动更新 .env 并重启服务

手动方式 2：浏览器提取 JWT Token

1. 打开浏览器开发者工具 Network 标签
2. 访问 https://suno.com/create 并触发 API 请求
3. 找到 studio-api.prod.suno.com 请求
4. 复制 Authorization: Bearer xxx 中的 token
5. 运行 update_token.py "<TOKEN>" 手动更新

方式 3：使用 setup-cookie.js 交互式配置工具

---

注意事项

1. [Intro] 和 [Outro] 下面不要加任何文本
2. JSON 转义: 歌词换行用 \n，引号用 \"
3. 歌词长度: 保持合理范围，过长可能被截断
4. 模型选择: 默认 V5 (chirp-crow) 质量最佳