英文 | 简体中文 | 俄语 | 演示 | 文档 | 通过 Vercel 部署

🔥 欢迎查看我的新项目：Linkly-ai-cli：专为 AI 代理打造的文档搜索引擎 CLI。

简介

Suno 是一款令人惊叹的 AI 音乐服务。尽管官方 API 尚未推出，我们仍迫不及待地希望将其功能整合到其他地方。

我们发现一些用户也有类似的需求，因此决定将此项目开源，希望能得到大家的喜爱。

该实现使用付费的 2Captcha 服务（又称 ruCaptcha）自动解决 hCaptcha 挑战，并且不依赖任何现成的闭源付费 Suno API 实现。

演示

我们部署了一个绑定免费 Suno 账户的示例，因此每日使用次数有限，但你可以看到它的运行情况： suno.gcui.ai

功能

• 完美实现了 suno.ai 的创作 API。
• 自动保持账户活跃。
• 使用 2Captcha 和 Playwright 结合 rebrowser-patches 自动解决 CAPTCHA。
• 兼容 OpenAI 的 /v1/chat/completions API 格式。
• 支持自定义模式。
• 一键部署至 Vercel 和 Docker。
• 除了标准 API 外，还适配了 GPTs 和 Coze 等代理平台的 API Schema，因此你可以将其用作 LLM 的工具/插件/Action，并集成到任何 AI 代理中。
• 采用宽松的开源许可协议，允许你自由集成和修改。

快速开始

1. 获取你的 Suno 账户 Cookie

1. 使用浏览器访问 suno.com/create。
2. 打开浏览器控制台：按下 F12 或进入“开发者工具”。
3. 切换到“网络”选项卡。
4. 快速刷新页面。
5. 找到包含关键词 ?__clerk_api_version 的最新请求。
6. 点击该请求，切换到“标头”选项卡。
7. 查找“Cookie”部分，将鼠标悬停在其上，复制 Cookie 的值。

2. 注册 2Captcha 并充值余额

2Captcha 是一项付费的 CAPTCHA 解决服务，它通过真人工作人员来解决 CAPTCHA，准确率很高。由于 Suno 不断要求解决 hCaptcha，而目前没有任何免费方式可以做到这一点，因此需要使用这项服务。

注册 一个新的 2Captcha 账户，充值 余额，并获取 API 密钥。

[!注意] 如果你位于俄罗斯或白俄罗斯，请使用 ruCaptcha 接口，而不是 2Captcha。两者是同一项服务，但 ruCaptcha 支持来自这些国家的支付。

[!提示] 如果你希望尽量减少 CAPTCHA 出现的次数，建议使用 macOS 系统。macOS 系统通常比 Linux 和 Windows 更少遇到 CAPTCHA——这主要是因为 macOS 在网络爬虫行业中并不流行。在 Windows 和 Linux 上运行 suno-api 也是可行的，但在某些情况下，你可能会遇到相当多的 CAPTCHA。

3. 克隆并部署该项目

你可以选择你喜欢的部署方式：

部署至 Vercel

本地运行

git clone https://github.com/gcui-art/suno-api.git
cd suno-api
npm install

Docker

[!重要] Docker 中将禁用 GPU 加速。如果你的 CPU 较慢，建议 本地部署。

你也可以使用 Docker Compose。不过，在运行之前请先执行以下步骤。

docker compose build && docker compose up

4. 配置 suno-api

• 如果部署到 Vercel，请在 Vercel 控制面板中添加环境变量。
• 如果你在本地运行，请务必在 .env 文件中添加以下内容：

环境变量

• SUNO_COOKIE — 第一步中获取的 Cookie 标头。
• TWOCAPTCHA_KEY — 第二步中获得的 2Captcha API 密钥。
• BROWSER — 用于解决 CAPTCHA 的浏览器名称。仅支持 chromium 和 firefox。
• BROWSER_GHOST_CURSOR — 使用 ghost-cursor-playwright 模拟平滑的鼠标移动。请注意，这似乎并不会影响 CAPTCHA 的出现频率，因此你可以将其设置为 false。保留此项以供未来测试。
• BROWSER_LOCALE — 浏览器的语言。建议使用 en 或 ru，因为这两个语言在 2Captcha 上有最多的工人。支持的语言列表
• BROWSER_HEADLESS — 无窗口运行浏览器。你可能希望将其设置为 true。

SUNO_COOKIE=<…>
TWOCAPTCHA_KEY=<…>
BROWSER=chromium
BROWSER_GHOST_CURSOR=false
BROWSER_LOCALE=en
BROWSER_HEADLESS=true

5. 运行 suno-api

• 如果你已部署到 Vercel：
  • 请在 Vercel 控制台中点击“Deploy”，并等待部署成功。
  • 访问 https://<vercel-assigned-domain>/api/get_limit API 进行测试。
• 如果在本地运行：
  • 运行 npm run dev。
  • 访问 http://localhost:3000/api/get_limit API 进行测试。
• 如果返回以下结果：

{
  "credits_left": 50,
  "period": "day",
  "monthly_limit": 50,
  "monthly_usage": 50
}

则表示程序运行正常。

6. 使用 Suno API

你可以查看详细的 API 文档，地址为： suno.gcui.ai/docs

API 参考

Suno API 目前主要实现了以下 API：

- `/api/generate`: 生成音乐
- `/v1/chat/completions`: 生成音乐 - 以与 OpenAI API 兼容的格式调用 generate API。
- `/api/custom_generate`: 生成音乐（自定义模式，支持设置歌词、音乐风格、标题等）
- `/api/generate_lyrics`: 根据提示词生成歌词
- `/api/get`: 根据 ID 获取音乐信息。多个 ID 之间用逗号分隔。如果不提供 ID，则返回所有音乐。
- `/api/get_limit`: 获取配额信息
- `/api/extend_audio`: 延长音频时长
- `/api/generate_stems`: 制作分轨音源（分离人声和伴奏）
- `/api/get_aligned_lyrics`: 获取歌词中每个单词的时间戳列表
- `/api/clip`: 根据查询参数 `id` 传入的 ID 获取片段信息
- `/api/concat`: 从片段生成完整歌曲

你还可以在请求的 Cookie 头中指定 cookies，覆盖 SUNO_COOKIE 环境变量中的默认 cookies。这在例如你想同时使用多个免费账号时非常有用。

如需更详细的文档，请访问演示站点： suno.gcui.ai/docs

API 集成代码示例

Python

import time
import requests

# 替换为你自己的 suno-api URL
base_url = 'http://localhost:3000'


def custom_generate_audio(payload):
    url = f"{base_url}/api/custom_generate"
    response = requests.post(url, json=payload, headers={'Content-Type': 'application/json'})
    return response.json()


def extend_audio(payload):
    url = f"{base_url}/api/extend_audio"
    response = requests.post(url, json=payload, headers={'Content-Type': 'application/json'})
    return response.json()

def generate_audio_by_prompt(payload):
    url = f"{base_url}/api/generate"
    response = requests.post(url, json=payload, headers={'Content-Type': 'application/json'})
    return response.json()


def get_audio_information(audio_ids):
    url = f"{base_url}/api/get?ids={audio_ids}"
    response = requests.get(url)
    return response.json()


def get_quota_information():
    url = f"{base_url}/api/get_limit"
    response = requests.get(url)
    return response.json()

def get_clip(clip_id):
    url = f"{base_url}/api/clip?id={clip_id}"
    response = requests.get(url)
    return response.json()

def generate_whole_song(clip_id):
    payload = {"clip_id": clip_id}
    url = f"{base_url}/api/concat"
    response = requests.post(url, json=payload)
    return response.json()


if __name__ == '__main__':
    data = generate_audio_by_prompt({
        "prompt": "一首关于战争的流行重金属歌曲，由低沉男声演唱，节奏缓慢而富有旋律感。歌词描绘了战后人们的悲痛。",
        "make_instrumental": False,
        "wait_audio": False
    })

    ids = f"{data[0]['id']},{data[1]['id']}"
    print(f"ids: {ids}")

    for _ in range(60):
        data = get_audio_information(ids)
        if data[0]["status"] == 'streaming':
            print(f"{data[0]['id']} ==> {data[0]['audio_url']}")
            print(f"{data[1]['id']} ==> {data[1]['audio_url']}")
            break
        # 暂停5秒
        time.sleep(5)

JavaScript

const axios = require("axios");

// 替换你的 Vercel 域名
const baseUrl = "http://localhost:3000";

async function customGenerateAudio(payload) {
  const url = `${baseUrl}/api/custom_generate`;
  const response = await axios.post(url, payload, {
    headers: { "Content-Type": "application/json" },
  });
  return response.data;
}

async function generateAudioByPrompt(payload) {
  const url = `${baseUrl}/api/generate`;
  const response = await axios.post(url, payload, {
    headers: { "Content-Type": "application/json" },
  });
  return response.data;
}

async function extendAudio(payload) {
  const url = `${baseUrl}/api/extend_audio`;
  const response = await axios.post(url, payload, {
    headers: { "Content-Type": "application/json" },
  });
  return response.data;
}

async function getAudioInformation(audioIds) {
  const url = `${baseUrl}/api/get?ids=${audioIds}`;
  const response = await axios.get(url);
  return response.data;
}

async function getQuotaInformation() {
  const url = `${baseUrl}/api/get_limit`;
  const response = await axios.get(url);
  return response.data;
}

async function getClipInformation(clipId) {
  const url = `${baseUrl}/api/clip?id=${clipId}`;
  const response = await axios.get(url);
  return response.data;
}

async function main() {
  const data = await generateAudioByPrompt({
    prompt:
      "一首关于战争的流行重金属歌曲，由低沉男声演唱，节奏缓慢而富有旋律感。歌词描绘了战后人们的悲痛。",
    make_instrumental: false,
    wait_audio: false,
  });

  const ids = `${data[0].id},${data[1].id}`;
  console.log(`ids: ${ids}`);

  for (let i = 0; i < 60; i++) {
    const data = await getAudioInformation(ids);
    if (data[0].status === "streaming") {
      console.log(`${data[0].id} ==> ${data[0].audio_url}`);
      console.log(`${data[1].id} ==> ${data[1].audio_url}`);
      break;
    }
    // 暂停5秒
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

main();

与自定义智能体集成

你可以将 Suno AI 作为工具/插件/动作集成到你的 AI 代理中。

与 GPTs 集成

[即将推出...]

与 Coze 集成

[即将推出...]

与 LangChain 集成

[即将推出...]

贡献

你可以通过以下四种方式支持本项目：

1. 分支并提交 Pull 请求：我们欢迎任何增强功能、API、响应时间和可用性的 PR。你也可以仅仅通过将此 README 翻译成你的语言来帮助我们——对本项目的任何帮助我们都十分欢迎！
2. 提出问题：我们感谢合理的建议和错误报告。
3. 捐赠：如果该项目对你有所帮助，请考虑使用项目顶部的赞助按钮为我们买杯咖啡。干杯！☕
4. 宣传：向他人推荐该项目，给仓库加星，或在使用项目后添加反向链接。

问题、建议、疑问或Bug？

我们使用 GitHub Issues 来管理反馈。欢迎随时提交Issue，我们会尽快处理。

许可证

本项目的许可证为 LGPL-3.0 或更高版本。更多信息请参阅 LICENSE 文件。

相关链接

• 项目仓库：github.com/gcui-art/suno-api
• Suno.ai 官方网站：suno.ai
• 演示：suno.gcui.ai
• Readpo：ReadPo 是一款由AI驱动的阅读与写作助手。以闪电般的速度收集、整理和创作内容。
• Album AI：自动生成图片元数据，并与相册进行对话。RAG + Album。

声明

suno-api 是一个非官方的开源项目，仅用于学习和研究目的。

Suno-API 快速上手指南

Suno-API 是一个开源项目，允许你通过 API 调用 Suno.ai 的音乐生成能力，并轻松集成到 GPTs、Coze 等 AI Agent 平台中。由于 Suno 官方尚未开放 API，本项目通过自动化技术（结合 2Captcha 验证码解决服务）实现了非官方的 API 封装。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：推荐 macOS（验证码触发频率较低），Linux 和 Windows 也可用。
• 运行环境：
  • Node.js (建议 v18+)
  • npm 或 pnpm
  • Docker (可选，用于容器化部署)
• 必要账号与密钥：
  1. Suno 账号 Cookie：你需要一个有效的 Suno.ai 账号。
  2. 2Captcha API Key：该项目依赖 2Captcha (或俄罗斯的 ruCaptcha) 来自动解决 hCaptcha 验证码。这是一个付费服务，需注册并充值获取 API Key。
     • 注意：目前无法免费绕过 Suno 的验证码机制。

安装步骤

第一步：获取 Suno Cookie

1. 浏览器访问 suno.com/create 并登录。
2. 按 F12 打开开发者工具，切换到 Network (网络) 标签页。
3. 刷新页面。
4. 在请求列表中找到包含 ?__clerk_api_version 的最新请求。
5. 点击该请求，在右侧 Headers (标头) 标签页中找到 Cookie 字段，复制其值。

第二步：配置环境变量

你可以选择本地运行或 Vercel 部署，均需配置以下变量：

• SUNO_COOKIE: 第一步中获取的 Cookie 字符串。
• TWOCAPTCHA_KEY: 你的 2Captcha API Key。
• BROWSER: 浏览器类型，仅支持 chromium 或 firefox。
• BROWSER_LOCALE: 浏览器语言，推荐 en 或 ru（2Captcha 工人较多）。
• BROWSER_HEADLESS: 是否无头模式运行，推荐 true。
• BROWSER_GHOST_CURSOR: 模拟平滑鼠标移动，可设为 false。

第三步：部署项目

方式 A：本地运行 (推荐开发调试)

1. 克隆项目：

   git clone https://github.com/gcui-art/suno-api.git
   cd suno-api
   npm install
   

2. 创建 .env 文件并填入配置：

   SUNO_COOKIE=<你的 Suno Cookie>
   TWOCAPTCHA_KEY=<你的 2Captcha Key>
   BROWSER=chromium
   BROWSER_GHOST_CURSOR=false
   BROWSER_LOCALE=en
   BROWSER_HEADLESS=true
   

3. 启动服务：

   npm run dev
   

方式 B：Docker 部署

注意：Docker 模式下 GPU 加速将被禁用。如果 CPU 性能较弱，建议使用本地运行方式。

docker compose build && docker compose up

方式 C：一键部署到 Vercel

点击下方按钮即可快速部署，并在 Vercel 控制面板中填写上述环境变量：

基本使用

部署完成后，可通过 HTTP 请求调用 API。

1. 验证服务状态

访问 http://localhost:3000/api/get_limit (本地) 或你的 Vercel 域名对应接口。若返回如下 JSON，说明服务正常：

{
  "credits_left": 50,
  "period": "day",
  "monthly_limit": 50,
  "monthly_usage": 50
}

2. 生成音乐示例 (Python)

以下是最简单的通过提示词生成音乐的流程：

import time
import requests

# 替换为你的服务地址
base_url = 'http://localhost:3000'

def generate_audio_by_prompt(payload):
    url = f"{base_url}/api/generate"
    response = requests.post(url, json=payload, headers={'Content-Type': 'application/json'})
    return response.json()

def get_audio_information(audio_ids):
    url = f"{base_url}/api/get?ids={audio_ids}"
    response = requests.get(url)
    return response.json()

if __name__ == '__main__':
    # 1. 发起生成请求
    data = generate_audio_by_prompt({
        "prompt": "A popular heavy metal song about war, sung by a deep-voiced male singer, slowly and melodiously.",
        "make_instrumental": False,
        "wait_audio": False
    })

    # 获取任务 ID
    ids = f"{data[0]['id']},{data[1]['id']}"
    print(f"Task IDs: {ids}")

    # 2. 轮询查询生成状态
    for _ in range(60):
        data = get_audio_information(ids)
        if data[0]["status"] == 'streaming':
            print(f"生成成功!")
            print(f"音频 1: {data[0]['audio_url']}")
            print(f"音频 2: {data[1]['audio_url']}")
            break
        time.sleep(5)

3. 主要 API 端点

• /api/generate: 根据提示词生成音乐。
• /api/custom_generate: 自定义模式生成（支持指定歌词、风格、标题等）。
• /api/get: 根据 ID 查询音乐信息。
• /api/get_limit: 查询配额使用情况。
• /v1/chat/completions: 兼容 OpenAI 格式的生成接口，方便接入 LLM Agent。

更多详细文档请访问：suno.gcui.ai/docs