Suno API 中文文档 — AI 音乐生成、歌词与音频

Suno API 是面向开发者的 AI 音乐生成接口，支持通过文字描述生成完整歌曲、歌词和音频轨道。通过 TTAPI 统一网关，你可以稳定访问最新 Suno 模型（包括 Suno v5.5 / chirp-v5-5），实现音乐创作、人声分离（分轨）和异步任务处理。本文档涵盖全部 Suno API 端点、工作流模式与集成指南。如果你想最快跑通一个可运行的集成，建议先看 Suno API Quickstart。

第一次使用 Suno API？ 直接跳到端到端完整示例，3 分钟内看完生成 → 查询的完整流程。

什么是 Suno API

Suno API 允许开发者向 Suno AI 音乐模型发送文本提示，并获得包含人声、伴奏和歌词的完整音频轨道。不同于基础的音乐循环生成器，Suno API 能从单个提示词生成完整的、接近专业品质的歌曲。通过 TTAPI，你还可以获得：

Suno v5 / chirp-v5 最新旗舰模型的访问能力
统一鉴权的标准 REST API，请求结构一致
通过轮询或 Webhook 回调处理的异步任务机制
分轨分离、歌词生成、音乐续写、风格翻唱等后处理能力
跨所有 AI 音频模型的统一计费与配额管理

快速开始

Suno API Quickstart — 最快路径，直接跑通集成
音乐生成 API — 提交歌曲生成任务
Fetch V2 API（获取结果） — 轮询异步任务结果
Suno 异步工作流指南 — 深入了解任务处理机制
Audio 计费说明 — 各接口的积分消耗

核心功能

🎵 AI 音乐生成（Suno v5.5）

使用最新 Suno 模型（包括 chirp-v5-5）从文本提示生成完整音乐轨道。支持有声和纯器乐输出、音乐续写与风格控制，适用于任何规模的 AI 音乐应用。

⚡ 异步可扩展工作流

异步提交生成任务，通过轮询或 Webhook 回调获取结果。这种异步优先的设计能高效处理长时任务，并能无缝集成到生产后端。

🎚️ 分轨与人声分离

将生成的音频分离为人声和伴奏轨道，用于混音、剪辑、翻唱制作或集成到专业音频流水线。

🎼 歌词生成与自定义模式

在生成音乐之前先生成歌词，或在自定义模式下提供你自己的歌词。Suno 歌词 API 会将歌词内容与人声时序对齐，无缝衔接完整歌曲生成流程。

🧩 开发者友好的 REST API

简洁的 RESTful 端点，请求与响应结构清晰。专为快速集成设计，兼容任何后端技术栈 — Node.js、Python、Go 或任何 HTTP 客户端。

鉴权与基础地址

所有 Suno API 请求均通过 TTAPI 网关，使用统一的鉴权方式。

配置项	值
Base URL	`https://api.ttapi.io`
鉴权 Header	`TT-API-KEY: YOUR_API_KEY`
Content-Type	`application/json`

完整设置说明请参考网关与鉴权。

端到端完整示例

最简生产可用的 Suno API 流程只需三步：

提交 POST /suno/v1/music
保存响应中的 data.jobId
将 jobId 传给 GET /suno/v2/fetch 获取结果

第一步 — 提交音乐生成请求

curl --request POST 'https://api.ttapi.io/suno/v1/music' \
  --header 'Content-Type: application/json' \
  --header 'TT-API-KEY: YOUR_TTAPI_KEY' \
  --data-raw '{
    "custom": true,
    "instrumental": false,
    "mv": "chirp-v5",
    "title": "深夜驾驶",
    "tags": "synthwave, 女声, 电影感",
    "prompt": "[Verse] 雨夜霓虹灯下的街道"
  }'

第二步 — 读取即时响应

{
  "status": "SUCCESS",
  "message": "success",
  "data": {
    "jobId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

立即保存 data.jobId。这是所有后续操作的唯一句柄：轮询、Webhook 对账、续写、翻唱、分轨和 WAV 导出都依赖它。

第三步 — 获取生成结果

curl --request GET 'https://api.ttapi.io/suno/v2/fetch?jobId=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'TT-API-KEY: YOUR_TTAPI_KEY'

任务处理中时，响应的 status 为 ON_QUEUE。生成完成后：

{
  "status": "SUCCESS",
  "message": "success",
  "jobId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "jobId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "action": "music",
    "progress": "100%",
    "mv": "chirp-v5",
    "quota": "6",
    "hookUrl": "https://your-app.example.com/webhooks/suno",
    "musics": [
      {
        "musicId": "xxxxxxxxxxxxxxxxx",
        "prompt": "[Verse] 雨夜霓虹灯下的街道",
        "title": "深夜驾驶",
        "tags": "synthwave, 女声, 电影感",
        "imageUrl": "https://cdn2.suno.ai/xxxxxxxxxxxxxxxxx.jpeg",
        "imageLargeUrl": "https://cdn2.suno.ai/xxxxxxxxxxxxxx.jpeg",
        "audioUrl": "https://cdn1.suno.ai/xxxxxxxxxxxxxxx.mp3",
        "videoUrl": "https://cdn1.suno.ai/xxxxxxxxxxxxxxx.mp4",
        "duration": 211.44,
        "negativeTags": "",
        "styleWeight": null,
        "weirdnessConstraint": null,
        "audioWeight": null,
        "createdAt": "2026-03-03T02:23:51.401Z"
      }
    ]
  }
}

对于大多数生产应用，最小实现是：提交 → 保存 jobId → 轮询 Fetch → 持久化 audioUrl、videoUrl、musicId 及元数据，供后续操作使用。

API 参数说明

核心生成参数（`POST /suno/v1/music`）

参数	类型	说明
`mv`	string	模型版本。使用 `chirp-v5-5` 获取最新 Suno v5.5 模型。
`prompt`	string	歌词内容或风格描述，作为 AI 音乐生成的输入。
`tags`	string	音乐风格标签，例如 `synthwave, 女声, 电影感`。
`title`	string	生成歌曲的标题。
`custom`	boolean	`true` 使用自定义歌词模式；`false` 为全 AI 生成内容。
`instrumental`	boolean	`true` 生成无人声的纯器乐。
`hookUrl`	string	可选。Webhook 回调地址，任务完成后 TTAPI 主动推送结果，无需轮询。

高级音频参数

参数	类型	说明
`weirdnessConstraint`	number	控制 AI 生成结果偏离传统音乐模式的程度。值越高，输出越实验性、越非常规；值越低，结果越贴近标准曲式和流派惯例。该字段也会出现在 Fetch 结果的 `musics` 数组中。
`styleWeight`	number	控制风格标签相对于 prompt 对生成结果的影响权重。
`audioWeight`	number	在适用场景下，平衡音频保真度与生成速度。
`negativeTags`	string	需要在生成结果中抑制或避免的风格标签。

全部接口列表

使用场景	接口页面
从文本提示生成完整歌曲	Suno 音乐生成 API
生成音乐前先写歌词	Suno 歌词生成 API
续写并延长已有曲目	Suno Extend API
将歌曲转为新风格	Suno Cover API
上传参考音频素材	Suno Upload API
分离人声与伴奏（双轨）	Suno Stems API
全轨多轨分离	Suno Stems All API
查询异步任务状态与结果	Suno Fetch V2 API
为编曲添加人声层	Suno Add Vocals API
导出高质量 WAV 格式	Suno WAV API
Mashup 混搭多首歌曲	Suno Mashup API
样本片段生成完整歌曲	Suno Sample to Song API
生成 MIDI 文件	Suno MIDI API
替换歌曲中的某一段落	Suno Replace Section API
裁剪已有歌曲片段	Suno Crop API
删除歌曲中的指定时间片段	Suno Remove Section API
为歌曲添加淡入效果	Suno Fade In API
为歌曲添加淡出效果	Suno Fade Out API
调整歌曲速度并可保持音高	Suno Adjust Speed API
拼接多段音轨	Suno Concatenate Track API
生成音效	Suno Sounds API
对齐歌词与音频时序	Suno Aligned Lyrics API
生成 MV 视频	Suno Generate Video API
创建自定义音色	Suno Create Voice API
BPM 分析	Suno BPM Analysis API

常见工作流

工作流	推荐路径
文本提示 → 完整歌曲	Lyrics（可选）→ Music → Fetch V2
参考音频 → 新生成	Upload → 下游接口 → Fetch V2
续写优秀草稿	Extend → Fetch V2
翻唱 / 风格重做	Cover → Fetch V2
提取人声或伴奏	Stems 或 Full Stems
混搭多首歌曲	Upload → Mashup → Fetch V2

轮询 vs Webhook：如何选择异步模式

大多数 Suno API 工作流都是异步的，获取结果有两种方式： 轮询 Fetch：循环调用 GET /suno/v2/fetch?jobId=...，直到 status 变为 SUCCESS。上手简单，任何 HTTP 客户端均可使用，推荐调试阶段使用。建议轮询间隔 3–5 秒。 Webhook 回调：在生成请求中传入 hookUrl，任务完成后 TTAPI 主动 POST 结果到你的端点。后端已有公开回调地址的生产系统推荐使用。完整的异步设计说明请参考 Suno API 异步工作流。

错误码与排查

状态码	错误信息	说明与处理
`400`	`Job not exits.` / `mv cannot be empty.` 等	请求参数错误，检查并修正参数后重试。
`400`	`Request parameter type mismatch`	请求体格式错误或参数类型不匹配，验证 JSON 结构。
`400`	`A technical issue with Suno is affecting everyone...`	Suno 官方异常或维护中，延迟后重试。
`401`	`Wrong TT-API-KEY or email is not activated.`	API Key 无效或账号邮箱未激活。
`402`	`Insufficient balance in TT API.`	TTAPI 账户余额不足，请充值。
`403`	`Authorized Error:[Account Block]`	调用账户已被封禁，请联系支持团队。
`404`	`Interface Not Found`	请求路径未命中有效端点，检查 URL。
`405`	`Request method not supported`	HTTP 方法错误，检查 `GET` 与 `POST` 的区别。
`415`	`Content type not supported`	请求头中设置 `Content-Type: application/json`。
`429`	`Too Many Requests`	被限流，加入指数退避重试逻辑。
`499`	`You have reached the maximum of suno job queues.`	Suno 队列已满，稍后重试，勿频繁轰炸端点。
`500`	`Submission failed, system exception.`	服务端异常，持续出现请联系 TTAPI 团队。

快速排查清单：

400 / 404 / 405 / 415：检查请求路径、HTTP 方法、JSON 结构和 Content-Type 请求头。
401 / 402 / 403：检查 TT-API-KEY 有效性、账号激活状态、封禁状态和余额。
429 / 499：加入指数退避重试，不要持续轰炸端点。
500：等待后重试，如持续出现请联系 TTAPI 团队。

为什么选择 TTAPI 接入 Suno API

统一网关 — 通过单一 API Key 和 Base URL 访问 Suno 及其他 AI 模型
持续跟进最新模型 — 始终支持最新 Suno 版本，包括 chirp-v5
标准化异步工作流 — 一致的任务提交、Fetch 轮询和 Webhook 回调模式
清晰的文档结构 — 概览指南与端点参考分离，开发效率更高
统一计费 — 跨所有音频和 AI API 的统一配额管理
生产就绪 — 稳定的请求处理与可扩展基础设施，支持高并发场景

常见问题

什么是 Suno API？

Suno API 是基于 Suno 模型的 AI 音乐生成开发者接口。它接受文字提示，返回包含人声、伴奏和歌词的完整音频轨道。通过 TTAPI，还支持异步工作流、Webhook 回调、分轨分离和多格式音频导出。

如何用 Suno API 生成音乐？

向 Suno 音乐生成 API 提交 POST 请求，带上 prompt、风格标签和模型版本（最新 Suno v5 使用 chirp-v5）。保存返回的 jobId，再通过 Suno Fetch V2 API 或 Webhook 获取生成的音频。

应该用哪个 Suno 模型？

推荐使用 chirp-v5-5（Suno v5.5），它提供最高质量的人声输出、最佳曲式结构和最长的生成时长。完整的 mv 参数可选值请参考音乐 API 参考。

`weirdnessConstraint` 参数是什么意思？

该参数控制 AI 生成结果偏离传统音乐模式的程度。值越高，输出越实验性和非常规；值越低，结果越贴近标准曲式和流派惯例。可在提交生成请求时设置，也会出现在 Fetch 结果的每个 musics 条目中。

如何查询任务状态？

使用 Suno Fetch V2 API 传入 jobId 轮询状态。处理中时 status 返回 ON_QUEUE；完成后 status 返回 SUCCESS，响应中包含完整的音频 URL。

Suno API 支持 Webhook 吗？

支持。提交任何 Suno 任务时传入 hookUrl 参数，TTAPI 会在任务完成后通过 HTTP POST 将结果推送到你的端点，无需轮询。完整 Webhook 实现说明请参考 Suno API 异步工作流。

可以生成无人声的纯器乐吗？

可以。在音乐生成请求中设置 "instrumental": true，Suno API 将生成不含任何人声的完整音轨。

可以上传自己的音频作为参考吗？

可以。使用 Suno Upload API 上传源音频或参考素材，再将其传入下游生成接口。

可以分离生成曲目中的人声和器乐吗？

可以。使用 Suno Stems API 进行双轨分离（人声 + 伴奏），或使用 Suno Stems All API 进行全轨多轨分离。

支持哪些编程语言？

TTAPI 提供标准 REST 接口，任何能发送 HTTP 请求的语言均可接入，包括 Python、Node.js、Go、Java、PHP 等。各语言接入示例请参考 Quickstart。

接下来应该看哪些页面？

从 Suno API Quickstart 开始，再深入音乐生成 API 和 Fetch V2 API 掌握核心的生成与查询流程。如需了解异步设计决策，阅读 Suno API 异步工作流。

​Suno API 中文文档 — AI 音乐生成、歌词与音频

​什么是 Suno API

​快速开始

​核心功能

​🎵 AI 音乐生成（Suno v5.5）

​⚡ 异步可扩展工作流

​🎚️ 分轨与人声分离

​🎼 歌词生成与自定义模式

​🧩 开发者友好的 REST API

​鉴权与基础地址

​端到端完整示例

​第一步 — 提交音乐生成请求

​第二步 — 读取即时响应

​第三步 — 获取生成结果

​API 参数说明

​核心生成参数（POST /suno/v1/music）

​高级音频参数

​全部接口列表

​常见工作流

​轮询 vs Webhook：如何选择异步模式

​推荐首次生产接入路径

​错误码与排查

​为什么选择 TTAPI 接入 Suno API

​常见问题

​什么是 Suno API？

​如何用 Suno API 生成音乐？

​应该用哪个 Suno 模型？

​weirdnessConstraint 参数是什么意思？

​如何查询任务状态？

​Suno API 支持 Webhook 吗？

​可以生成无人声的纯器乐吗？

​可以上传自己的音频作为参考吗？

​可以分离生成曲目中的人声和器乐吗？

​支持哪些编程语言？

​接下来应该看哪些页面？