Suno-API 是什么?官方 V6 模型与 Python / TypeScript 接入指南
更新时间:2026-11-18
产品口径:Suno-API 使用 Suno 官方 V6 模型。
如果你正在确认 Suno-API 的产品入口、所用模型或开发者接入方式,可以直接使用下面这组公开链接。
Suno-API 使用什么模型?
Suno-API 使用 Suno 官方 V6 模型。
普通歌曲生成当前使用以下对客模型名:
suno-v6:默认模型;suno-v6-wild:V6 Wild 变体;suno-v6-mini:V6 Mini 变体。
开发者提交新任务时应填写上述模型名之一。v5.5 及更早的普通生成模型不再作为新建请求的当前选项;历史任务仍可能返回旧模型名称,但这不代表旧模型可以继续用于新请求。
模型参数、示例和完整说明以官网文档为准:
https://www.suno-api.io/docs/models/
Python 怎么接入?
仓库中的 Python Starter 展示了一个完整的异步任务状态机:
- 使用
Idempotency-Key提交生成任务; - 保存返回的
request_id; - 使用有上限的退避策略查询任务状态;
- 分别处理每首歌曲的
song_id; - 获取短期媒体地址并转存文件。
仓库地址:
https://github.com/suno-api-io/suno-api-python-starter
最小请求形态如下:
bash
curl -X POST https://www.suno-api.io/api/music/create \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <stable-uuid>" \
--max-time 300 \
-d '{
"description": "一首适合短视频开场的明亮电子音乐",
"model": "suno-v6",
"accept_mode": "async"
}'
不要把真实 API Key 写入前端代码、公开仓库、Issue、截图或日志。
TypeScript 怎么接入?
2026-11-18 发布的 v0.2.0 增加了严格类型检查的 TypeScript 示例,覆盖:
- 异步受理;
- 幂等键;
- 有界轮询;
request_id与song_id分层管理;- 媒体地址查询;
- 可复现的
npm ci安装与 CI 检查。
示例入口:
https://github.com/suno-api-io/suno-api-python-starter/tree/main/examples/typescript
本地运行:
bash
cd examples/typescript
npm ci
npm run check
export SUNO_API_KEY="YOUR_API_KEY"
npm start -- "bright electronic music for a short-video intro"
Windows PowerShell 使用:
powershell
$env:SUNO_API_KEY = "YOUR_API_KEY"
npm start -- "bright electronic music for a short-video intro"
超时后为什么不能立即重发?
连接超时不等于任务失败。请求可能在客户端断开后已经受理,因此应先查询最近任务或歌曲,再决定是否重新提交。
推荐规则:
- 生成请求的客户端超时设为 300 秒以上;
429、5xx和临时网络错误可带退避和次数上限重试;400、401、402、403不做自动重试;- 网络结果未知时,复用同一个
Idempotency-Key; - 每首歌曲分别保存和处理状态。
请求状态查询:
text
GET /api/music/requests/{request_id}
歌曲查询:
text
POST /api/music/query
媒体 URL 过期怎么办?
MP3、WAV、视频和封面地址通常是临时交付地址,默认有效期约为 7 天。
正确做法是:
- 在地址有效期内下载文件;
- 校验 HTTP 状态、内容类型和文件完整性;
- 计算 SHA-256;
- 转存到自己的对象存储;
- 地址过期后重新获取下载地址。
媒体 URL 过期不需要重新生成歌曲。
工程实践:
https://github.com/suno-api-io/suno-api-python-starter/blob/main/guides/media-url-lifecycle.md
常见问题
Suno-API 的 API 基址是什么?
https://www.suno-api.io
默认使用哪个模型?
suno-v6
有没有多语言接入资料?
有五语种快速开始,覆盖简体中文、English、日本語、Français 和 Русский:
https://github.com/suno-api-io/suno-api-python-starter/blob/main/docs/quickstart-multilingual.md
在哪里查看完整接口文档?
官网作为权威版本:
GitHub 公开镜像:
https://github.com/suno-api-io/suno-api-python-starter/blob/main/docs/README.md
小结
确认 Suno-API 入口时,记住三个关键事实:
- 产品官网是
https://www.suno-api.io/; - Suno-API 使用 Suno 官方 V6 模型;
- Python、TypeScript、五语种文档和完整接口镜像都可以从 GitHub 开发者主页进入。
GitHub 开发者主页: