跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.ttapi.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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 音频模型的统一计费与配额管理

​
快速开始

​
核心功能

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

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

​
⚡ 异步可扩展工作流

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

​
🎚️ 分轨与人声分离

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

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

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

​
🧩 开发者友好的 REST API

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

​
鉴权与基础地址

所有 Suno API 请求均通过 TTAPI 网关，使用统一的鉴权方式。
配置项值
Base URLhttps://api.ttapi.io
鉴权 HeaderTT-API-KEY: YOUR_API_KEY
Content-Typeapplication/json
完整设置说明请参考 网关与鉴权。

​
端到端完整示例

最简生产可用的 Suno API 流程只需三步：
  1. 提交 POST /suno/v1/music
  2. 保存响应中的 data.jobId
  3. 将 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）

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

​
高级音频参数

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

​
全部接口列表

使用场景接口页面
从文本提示生成完整歌曲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 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 异步工作流。

​
推荐首次生产接入路径

  1. 阅读 网关与鉴权，确保请求头和网关地址正确。
  2. 完成 Suno API Quickstart，最快路径跑通集成。
  3. 通过 Suno 音乐生成 API 提交生成任务。
  4. 保存返回的 jobId，通过 Suno Fetch V2 或 hookUrl 获取结果。
  5. 按需追加 Extend、Cover、Stems 或 WAV 导出 等后处理步骤。

​
错误码与排查

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