OpenSuno

开源Suno AI API，带Chrome扩展桥-零配置验证和自动captcha旁路。采用Claude Code和Paean AI构建。

两种操作模式： 桥接模式 （Chrome扩展程序——推荐）和 Cookie模式 （服务器端）。

为什么选择OpenSuno？

问题1：Suno的API依赖Clerk会话进行身份验证，但Clerk经常返回空会话(sessions: [])，导致401个未经授权的错误。

问题2：当账户消耗的信用少于约200个时，Suno的API需要hCaptcha来生成音乐。服务器端方法失败，显示“令牌验证失败”（422），因为它们无法提供有效的验证码令牌。

解决方案：OpenSuno提供了两种方法：

桥接模式 （推荐）-Chrome扩展在suno.com上运行，从浏览器上下文调用API。身份验证和验证码是本机处理的。本地网桥服务器公开REST API+MCP接口，通过WebSocket将请求转发到扩展。
Cookie模式 --从浏览器中提取JWT令牌（有效，但需要手动刷新令牌，可能会碰到验证码块）

特性

Chrome扩展程序+桥接服务器 --零配置认证，自动绕过验证码，无令牌过期
MCP服务器 --用作Claude Desktop、Cursor或任何兼容MCP的AI代理的工具提供者
直接JWT令牌身份验证（Cookie模式）——从浏览器的“网络”选项卡中提取
支持所有Suno型号版本（V4/V4.5+/V4.5 Pro/V5）
OpenAI兼容 /v1/chat/completions 端点
基于Web的cookie管理UI /cookie
一键Vercel部署（Cookie模式）

桥接模式（推荐）

桥接模式使用Chrome扩展程序+本地桥接服务器。该扩展在您打开的suno.com选项卡上运行，本机处理身份验证和验证码。外部客户端（curl、AI代理）与网桥服务器通信，网桥服务器通过WebSocket将请求转发给扩展。

建筑

External Clients (curl, AI agents, etc.)
         │
         ▼
┌─────────────────────────┐
│   Bridge Server (Bun)   │
│   Port 3001             │
│  ┌───────────────────┐  │
│  │ REST API endpoints │  │  ← curl / HTTP clients
│  │ /api/generate etc  │  │
│  ├───────────────────┤  │
│  │ MCP Server         │  │  ← AI agents (Claude, Cursor)
│  │ /mcp (Streamable)  │  │
│  ├───────────────────┤  │
│  │ WebSocket /ws      │──│──┐
│  └───────────────────┘  │  │
└─────────────────────────┘  │  WebSocket
                              │
┌─────────────────────────┐  │
│  Chrome Extension        │  │
│  (on suno.com tab)       │◄─┘
│  ┌───────────────────┐  │
│  │ Content Script     │  │  → Orchestrates messaging
│  ├───────────────────┤  │
│  │ Page Script        │  │  → Accesses Clerk (JWT)
│  │ (MAIN world)       │  │    + hCaptcha tokens
│  ├───────────────────┤  │
│  │ Background Worker  │  │  → Makes API calls to Suno
│  │                    │  │    (bypasses CORS)
│  ├───────────────────┤  │
│  │ Popup (status UI)  │  │
│  └───────────────────┘  │
└─────────────────────────┘

它是如何工作的：

这 页面脚本 在suno.com的上下文中运行，访问 window.Clerk 对于JWT代币和 window.hcaptcha 用于验证码令牌
这 内容脚本 通过WebSocket在页面脚本、后台工作程序和网桥服务器之间进行编排
这 后台服务人员 对以下对象进行实际的fetch调用 studio-api.prod.suno.com （后台脚本绕过CORS）
这 网桥服务器 从外部客户端接收REST/MCP请求，并通过WebSocket将其转发到扩展

设置

1.安装依赖项并构建扩展

git clone https://github.com/paean-ai/opensuno.git
cd opensuno
bun install
bun run ext:build

这将构建扩展 extension/dist/.

2.加载Chrome扩展程序

打开 chrome://extensions/ 在Chrome浏览器中
启用 开发者模式 （右上角切换）
点击 加载未打包的
选择 extension/dist/ 目录

3. 打开 suno.com

打开https://suno.com/create在选项卡中，确保您已登录。扩展图标应显示徽章。

4.启动网桥服务器

bun run bridge

网桥服务器启动于 http://localhost:3001。扩展弹出窗口应显示连接.

5.测试一下

# Check connection status
curl http://localhost:3001/api/status

# Check credits
curl http://localhost:3001/api/get_limit

# Generate music (captcha handled automatically)
curl -X POST http://localhost:3001/api/custom_generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "sunshine and rainbows",
    "tags": "pop, upbeat",
    "title": "Happy Day"
  }'

桥接MCP服务器

网桥服务器包括一个内置的MCP端点，位于 /mcp （流式HTTP传输）。配置您的AI客户端：

克劳德代码 --编辑 ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "suno": {
      "type": "url",
      "url": "http://localhost:3001/mcp"
    }
  }
}

克劳德桌面 --编辑您的配置以添加远程MCP URL，或使用stdio模式（见下文）。

桥接脚本

bun run bridge          # Start bridge server (port 3001)
bun run bridge:dev      # Start with --watch (auto-restart on changes)
bun run ext:build       # Build extension to extension/dist/
bun run ext:watch       # Build extension with file watching

备注：重建扩展后，单击上的刷新按钮 chrome://extensions/ 然后 刷新suno.com选项卡 加载更新的脚本。

______________________________________________________________________

Cookie模式（备选）

1.安装依赖项

git clone https://github.com/paean-ai/opensuno.git
cd opensuno
bun install

2.获取JWT代币

选项A：Web UI（推荐）

首先启动服务器 bun dev，然后访问 http://localhost:3000/cookie 获取带有分步说明的指导性设置。

选项B：交互式CLI

打开https://suno.com/create在浏览器中登录
按 F12 打开开发人员工具
切换到网络标签
点击页面上的输入框（触发API请求）
查找任何 studio-api.prod.suno.com 网络列表中的请求
点击请求→ 标头 → 请求报头
复制两个值：

- authorization: Bearer xxx → 复制零件后 Bearer - cookie: xxx → 复制整个cookie字符串

运行安装脚本：

node setup-cookie.js

在提示时粘贴JWT令牌和Cookie。

选项C：手动配置

创建一个 .env 文件：

SUNO_COOKIE=__session=; __client=xxx; ajs_anonymous_id=xxx; ...

重要：确保后面的值 __session= 是从Authorization标头中提取的JWT令牌。

3.启动服务器

bun dev

服务器启动于http://localhost:3000.

4.测试API

# Check account credits
curl http://localhost:3000/api/get_limit

# Generate lyrics
curl -X POST http://localhost:3000/api/generate_lyrics \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a happy song about sunshine"}'

# Generate music
curl -X POST http://localhost:3000/api/custom_generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "sunshine and rainbows",
    "tags": "pop, upbeat",
    "title": "Happy Day"
  }'

支持的型号

版本	型号ID	常数	注释
V3.5	`chirp-v3-5`	`SUNO_MODELS.V3_5`	遗产
V4	`chirp-v4`	`SUNO_MODELS.V4`	—
V4.5+	`chirp-bluejay`	`SUNO_MODELS.V4_5_PLUS`	蓝鸟
V4.5专业版	`chirp-auk`	`SUNO_MODELS.V4_5_PRO`	奥克
版本5	`chirp-crow`	`SUNO_MODELS.V5`	乌鸦（默认）

要指定模型，请添加 "model": "chirp-bluejay" （或任何型号ID）发送到您的请求正文。

api参考

这些端点在桥接模式（端口3001）和Cookie模式（端口3000）下都可用：

方法	端点	描述
得到	`/api/get_limit`	获取剩余账户积分
职位	`/api/generate`	生成音乐（简单模式）
职位	`/api/custom_generate`	生成音乐（带有歌词/标签的自定义模式）
职位	`/api/generate_lyrics`	根据提示生成歌词
得到	`/api/get?ids=xxx`	按ID获取音乐详细信息
职位	`/api/extend_audio`	扩展音频片段
职位	`/api/generate_stems`	分成茎轨
职位	`/api/concat`	将扩展连接成一首完整的歌曲

仅限桥接模式：

方法	端点	描述
得到	`/api/status`	网桥连接状态和扩展信息
得到	`/api/captcha_check`	检查当前是否需要验证码
职位	`/mcp`	用于AI代理的MCP流式HTTP端点

仅Cookie模式：

方法	端点	描述
得到	`/api/get_aligned_lyrics`	获取单词级歌词时间戳
职位	`/v1/chat/completions`	OpenAI兼容音乐生成
得到	`/api/cookie`	检查当前cookie状态
职位	`/api/cookie`	将cookie保存到.env（用于本地部署）

完整的交互式文档可在 /docs 启动服务器后。

配置

环境变量

桥接模式：

# Optional — override bridge server port (default: 3001)
BRIDGE_PORT=3001

桥接模式不需要其他配置——auth和验证码由扩展处理。

Cookie模式：

# Required
SUNO_COOKIE=__session=; __client=xxx; ...

# Optional (CAPTCHA solving)
TWOCAPTCHA_KEY=your_2captcha_key

# Optional (browser config for CAPTCHA)
BROWSER=chromium                    # chromium | firefox
BROWSER_HEADLESS=true               # true | false
BROWSER_LOCALE=en                   # browser locale
BROWSER_GHOST_CURSOR=false          # use ghost cursor (more natural mouse movement)
BROWSER_DISABLE_GPU=false           # set to true for Docker environments

JWT令牌到期

JWT代币通常持续几个小时。当过期时，API返回401个错误。要修复：

访问https://suno.com/create再次
从网络请求中提取新的JWT令牌
通过更新 /cookie web UI或编辑 .env 直接

如果您提供 __client cookie，系统将尝试通过Clerk自动刷新令牌。

MCP服务器（模型上下文协议）

该项目包括用于桥接模式和Cookie模式的MCP服务器，允许AI代理（Claude Desktop、Cursor、Claude Code等）使用Suno作为工具提供商。

桥接模式MCP（推荐）

运行网桥服务器时(bun run bridge)，MCP端点位于 http://localhost:3001/mcp 使用流式HTTP传输。看桥接MCP服务器以上为配置。

Cookie模式MCP

可用的MCP工具

工具	说明
`get_credits`	检查剩余积分和使用限制
`generate`	从文本提示生成音乐
`custom_generate`	生成带有歌词、风格标签和标题的音乐
`generate_lyrics`	根据主题/主题生成歌词
`get_audio`	获取音频剪辑状态和详细信息
`extend_audio`	从时间戳扩展现有剪辑
`generate_stems`	将夹子分成阀杆轨道
`concat`	将扩展片段组合成一首完整的歌曲

本地模式（stdio）——用于克劳德桌面/光标/克劳德代码

这是在本地使用MCP的标准方式。AI客户端将服务器作为子进程启动，并通过stdin/stdout进行通信。

克劳德桌面 --编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "suno": {
      "command": "bun",
      "args": ["run", "src/mcp/stdio.ts"],
      "cwd": "/path/to/opensuno",
      "env": {
        "SUNO_COOKIE": "__session=xxx; __client=xxx; ..."
      }
    }
  }
}

光标 --转到“设置”→ 特性→ MCP → 添加服务器：

姓名： suno
类型： stdio
命令： bun run src/mcp/stdio.ts
工作目录： /path/to/opensuno

克劳德代码 --编辑 ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "suno": {
      "command": "bun",
      "args": ["run", "src/mcp/stdio.ts"],
      "cwd": "/path/to/opensuno",
      "env": {
        "SUNO_COOKIE": "__session=xxx; __client=xxx; ..."
      }
    }
  }
}

如果你有 .env 在项目目录中配置的文件，可以省略 env block--服务器读取 .env 自动。

云模式（流式HTTP）——用于远程代理

对于云部署或通过网络共享MCP服务器：

# Start the MCP HTTP server (default port 3001)
bun run mcp:http

# Or with a custom port
MCP_PORT=8080 bun run mcp:http

服务器监听 http://localhost:3001/mcp 并支持MCP流式HTTP传输（基于会话，支持SSE流式传输）。

远程MCP客户端可以使用以下方式连接：

端点： http://your-server:3001/mcp
传输：流式HTTP

运行Next.js API和MCP服务器

Next.js API服务器（端口3000）和MCP HTTP服务器（端口3001）是独立的-您可以同时运行这两个服务器：

# Terminal 1: Next.js API server
bun dev

# Terminal 2: MCP HTTP server
bun run mcp:http

码头工人

# Build
docker build -t opensuno .

# Run
docker run -d -p 3000:3000 \
  -e SUNO_COOKIE="__session=xxx; __client=xxx; ..." \
  opensuno

常见问题解答

Q：我应该使用哪种模式？ 使用 桥接模式 如果你在当地跑步。它自动处理身份验证和验证码，不需要令牌管理。使用 Cookie模式 适用于无法运行浏览器扩展的服务器/云部署。

Q：扩展显示“已断开连接”？ 确保网桥服务器正在运行(bun run bridge).检查扩展弹出窗口中的网桥URL是否匹配（默认值： ws://localhost:3001/ws).

Q： API调用在重新加载扩展后失败？ 在中重新加载扩展后 chrome://extensions/，你也必须 刷新suno.com选项卡 注入更新的脚本。

Q：为什么我的401未经授权？（Cookie模式） JWT令牌已过期或格式错误。检查一下 SUNO_COOKIE 以...开始 __session= 后面是来自Authorization标头的令牌。如果需要，请从浏览器中重新提取。

Q：我在哪里可以找到JWT代币？ 在浏览器中开发人员工具→ 网络选项卡，查找任何 studio-api.prod.suno.com 请求，查看请求标头，并在以下位置复制值 authorization: Bearer .

Q： Cookie太长，收到431错误？ cookie包含无关条目（谷歌、脸书等）。使用 /cookie web UI或 setup-cookie.js 它会自动过滤到仅与Suno相关的Cookie。

许可证

LGPL-3.0或更高版本——见许可证.

致谢

Suno AI --音乐生成服务

免责声明

本项目仅用于学习和研究目的。请遵守Suno.ai的服务条款。

opensuno (Paean AI)

快速接入

详细介绍