快速开始指南
5 分钟完成 Suno-API 接入：创建 API Key、提交歌曲、查询状态并下载 MP3/WAV。
打开你正在使用的 AI，复制下面这句话发送，即可由 AI 按 Agent Kit 引导完成接入。
请从这个地址下载安装配置 suno-api agent kit https://www.suno-api.io/suno-agent-kit.zip推荐接入：一句话交给 AI
如果不想逐页看接口，直接把上面的指令发给你正在使用的 AI。AI 下载并解压 Agent Kit 后，会先读取 00_START_HERE.md，再按下面的 onboarding 流程协助你完成接入。
- 检查你是否已经注册；如果没有，会先询问是否需要注册。
- 在你同意并提供用户名和密码后，协助完成注册，并把 API Key 保存在本地配置中。
- 注册完成后检查账户余额，询问是否需要充值，并引导打开控制台钱包：
https://www.suno-api.io/console/topup。 - 告知在线制作入口：
https://www.suno-api.io/create/。 - 告知修改密码入口：
https://www.suno-api.io/console/personal。 - 读取
MCP_GUIDE.md，介绍生成、翻唱、续写、分轨、音色等全部功能。 - 推荐先用简易模式生成一首歌，确认接入链路正常。
- 说明既可以由 AI 直接执行生成，也可以复用 SDK、CLI、Core 和扩展模块自行搭建系统。
- 所有收费操作执行前都会再次确认；请求超时不会自动重复提交，避免重复扣费。
- 提供客服信息：QQ 群
926975276、微信suno-api，服务时间北京时间9:00-23:00。
只在可信的 AI 环境中提供登录信息；API Key 应保存在本地配置中，不要公开到代码仓库、网页源码或聊天记录。
Suno API Key 怎么获取？ 本站使用 Suno 官方 V6 模型，提供 API Key。注册 Suno-API 账号后即可在控制台创建 Key，用来调用音乐生成、查询和下载接口。
当前普通歌曲生成默认模型为
suno-v6。suno-v2至suno-v5-5普通生成模型已下线，仅可能出现在历史任务中，不能用于新请求。模型选项和分轨说明请参阅支持的模型。
开发者示例： cURL / Postman 测试 · request_id 与 song_id 字段说明 · MP3 / WAV 下载与转存 · 批量生成、并发与重试 · 移动 App 背景音乐接入 · 端点地图 · 错误处理
Suno 模型 API 与 Key 获取
本站使用 Suno 官方模型提供 HTTP API。你无需自行申请 Suno 账号，在本站注册后即可创建 API Key，直接调用官方模型完成音乐生成；Key、计费和限流由本站统一管理。
拿到本站 Key 只要三步：
- 用邮箱注册并登录（不需要手机号，也不用绑卡）。
- 进入「控制台 → 令牌管理」，新建一个令牌。
- 复制这个令牌，它就是请求头里的
Authorization: Bearer YOUR_API_KEY；令牌只完整显示一次。
第一步：获取 API 密钥
- 访问 https://www.suno-api.io
- 点击中间的「获取密钥」按钮
- 注册或登录您的账号
- 在控制台-令牌管理中创建新的 API 密钥
- 复制并妥善保管您的密钥（密钥只显示一次）
- 在钱包管理中输入兑换码兑换额度（可前往闲鱼 winter宝宝 店铺购买兑换码）或点击该链接https://m.tb.cn/h.iHLa7gp?tk=rRy15RQvlpQ 直接前往购买
- 充值：点账号菜单里的「充值」，支持微信支付、兑换码，也可以从官方闲鱼店购买充值码后回来兑换
第二步：配置 API 基础信息
所有 API 请求都需要以下基础配置：
API 基址: https://www.suno-api.io
请求头:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
第三步：发起第一个请求
示例 1：灵感生成（最简单）
只需提供一句话描述，AI 会自动创作完整的歌曲：
curl -X POST https://www.suno-api.io/api/music/create \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "一首关于春天的轻快民谣",
"model": "suno-v6"
}'
响应示例:
[
{
"song_id": "abc123",
"status": "pending",
"song_title": "春日物语",
"description": "一首关于春天的轻快民谣",
"created_at": "2026-04-22T10:30:00Z"
},
{
"song_id": "def456",
"status": "pending",
"song_title": "春天的脚步",
"description": "一首关于春天的轻快民谣",
"created_at": "2026-04-22T10:30:00Z"
}
]
💡 提示: 每次生成通常会返回 2 首不同风格的歌曲供您选择。
示例 2：查询生成进度
使用返回的 song_id 查询音乐生成状态：
curl -X POST https://www.suno-api.io/api/music/query \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"song_ids": ["abc123", "def456"],
"model": "suno-v6"
}'
响应示例（生成中）:
[
{
"song_id": "abc123",
"status": "processing",
"song_title": "春日物语",
"progress": "60%"
}
]
响应示例（生成完成）:
[
{
"song_id": "abc123",
"status": "completed",
"song_title": "春日物语",
"audio_url": "https://cdn.suno-api.io/audio/abc123.mp3",
"video_url": "https://cdn.suno-api.io/video/abc123.mp4",
"cover_url": "https://cdn.suno-api.io/cover/abc123.jpg",
"lyrics": "春风吹过田野...",
"duration": 180.5,
"model_version": "suno-v6",
"created_at": "2026-04-22T10:30:00Z"
}
]
第四步：下载音乐文件
生成完成后，使用返回的 audio_url 直接下载 MP3 文件：
curl -O https://cdn.suno-api.io/audio/abc123.mp3
或在浏览器中直接访问该 URL 进行播放。
⚠️ 音频地址 7 天后失效，请及时转存：
audio_url、WAV 等媒体地址由平台的对象存储提供，默认 7 天后回收（旧地址会返回 404）。请在这 7 天内把文件转存到你自己的存储；过期后重新调用歌曲查询 API 即可拿到新的有效地址，不需要重新生成歌曲，也不会额外计费。
常见使用场景
场景 1：快速生成背景音乐
// Node.js 示例
const axios = require('axios');
async function generateMusic(description) {
const response = await axios.post(
'https://www.suno-api.io/api/music/create',
{
description: description,
model: 'suno-v6',
instrumental: true // 纯音乐，无人声
},
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
}
);
return response.data;
}
// 使用
generateMusic('轻松的咖啡厅背景音乐').then(songs => {
console.log('生成的歌曲ID:', songs.map(s => s.song_id));
});
场景 2：自定义歌词和风格
# Python 示例
import requests
def create_custom_song(lyrics, style, title):
response = requests.post(
'https://www.suno-api.io/api/music/create/custom',
json={
'lyrics': lyrics,
'style_tags': style,
'song_title': title,
'model': 'suno-v6',
'vocal_gender': 'male',
'style_weight': 0.75,
'weirdness_constraint': 0.25
},
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
)
return response.json()
# 使用
songs = create_custom_song(
lyrics='[Verse 1]\n春天来了\n花儿开了\n...',
style='pop, acoustic, cheerful',
title='春天的歌'
)
vocal_gender 支持 m、f、male、female；style_weight 和 weirdness_constraint 的范围均为 0.0 到 1.0。三个参数均可省略。
场景 3：轮询等待生成完成
// 轮询查询直到生成完成
async function waitForCompletion(songIds, maxWaitTime = 120000) {
const startTime = Date.now();
while (Date.now() - startTime < maxWaitTime) {
const response = await axios.post(
'https://www.suno-api.io/api/music/query',
{
song_ids: songIds,
model: 'suno-v6'
},
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
}
);
const songs = response.data;
const allCompleted = songs.every(s =>
s.status === 'completed' || s.status === 'failed'
);
if (allCompleted) {
return songs;
}
// 等待 5 秒后再次查询
await new Promise(resolve => setTimeout(resolve, 5000));
}
throw new Error('生成超时');
}
错误处理
常见错误码
| HTTP 状态码 | 说明 | 解决方案 |
|---|---|---|
| 401 | 未授权 | 检查 API 密钥是否正确 |
| 402 | 余额不足 | 请充值后继续使用 |
| 429 | 请求过于频繁 | 降低请求频率，建议间隔 1 秒 |
| 500 | 服务器错误 | 稍后重试或联系技术支持 |
错误响应示例
{
"success": false,
"message": "余额不足，请充值",
"error_code": "INSUFFICIENT_BALANCE"
}
连接超时不是失败信号。 生成类接口是同步接口，受理前不会有任何中间响应；客户端超时断开后，订单仍可能已经受理并正在生成，稍后能在
GET /api/music/songs里看到。请把客户端超时设置为 300 秒以上，断开后先确认再决定是否重新提交，避免重复扣费。详见新版 API 总览的「等待时间与超时设置」。
最佳实践
- 客户端超时: 生成类接口在返回时才算受理完成，请把客户端超时设置为 300 秒以上
- 异步处理: 音乐生成需要约 60 秒，建议使用异步方式处理
- 轮询间隔: 查询生成状态时，建议间隔 5-10 秒
- 错误重试: 只对明确的失败响应（4xx/5xx）重试；连接超时或中断时，先用
GET /api/music/songs确认订单是否已受理，避免重复下单与重复扣费 - 密钥安全: 不要在前端代码中暴露 API 密钥，应在后端调用
- 批量查询: 查询多首歌曲时，使用单次请求传入多个 song_ids
下一步
- 查看 灵感模式生成 API 详细文档
- 查看 专业模式生成 API 详细文档
- 了解 计费规则
需要帮助？
- 技术支持QQ群：926975276
- 在线文档: www.suno-api.io/docs