> ## 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 中文开发者文档。通过 REST API 生成 AI 音乐、歌曲和歌词。支持 Suno v5、异步任务、Webhook 回调与分轨分离。 # Suno API 中文文档 — AI 音乐生成、歌词与音频 **Suno API** 是面向开发者的 AI 音乐生成接口，支持通过文字描述生成完整歌曲、歌词和音频轨道。通过 TTAPI 统一网关，你可以稳定访问最新 Suno 模型（包括 **Suno v5.5 / chirp-v5-5**），实现音乐创作、人声分离（分轨）和异步任务处理。本文档涵盖全部 Suno API 端点、工作流模式与集成指南。 如果你想最快跑通一个可运行的集成，建议先看 [Suno API Quickstart](/grids/en/start/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](/grids/en/start/suno-api-quickstart) — 最快路径，直接跑通集成 * [音乐生成 API](/api/cn/suno/suno_music) — 提交歌曲生成任务 * [Fetch V2 API（获取结果）](/api/cn/suno/suno_fetch_v2) — 轮询异步任务结果 * [Suno 异步工作流指南](/grids/en/start/suno-api-async-workflow) — 深入了解任务处理机制 * [Audio 计费说明](/grids/cn/start/pricing/audio#suno) — 各接口的积分消耗 *** ## 核心功能 ### 🎵 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` | 完整设置说明请参考 [网关与鉴权](/grids/cn/development/authentication)。 *** ## 端到端完整示例 最简生产可用的 Suno API 流程只需三步： 1. 提交 `POST /suno/v1/music` 2. 保存响应中的 `data.jobId` 3. 将 `jobId` 传给 `GET /suno/v2/fetch` 获取结果 ### 第一步 — 提交音乐生成请求 ```bash theme={null} 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] 雨夜霓虹灯下的街道" }' ``` ### 第二步 — 读取即时响应 ```json theme={null} { "status": "SUCCESS", "message": "success", "data": { "jobId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ``` 立即保存 `data.jobId`。这是所有后续操作的唯一句柄：轮询、Webhook 对账、续写、翻唱、分轨和 WAV 导出都依赖它。 ### 第三步 — 获取生成结果 ```bash theme={null} curl --request GET 'https://api.ttapi.io/suno/v2/fetch?jobId=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \ --header 'TT-API-KEY: YOUR_TTAPI_KEY' ``` 任务处理中时，响应的 `status` 为 `ON_QUEUE`。生成完成后： ```json theme={null} { "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](/api/cn/suno/suno_music) | | 生成音乐前先写歌词 | [Suno 歌词生成 API](/api/cn/suno/suno_lyrics) | | 续写并延长已有曲目 | [Suno Extend API](/api/cn/suno/suno_extend) | | 将歌曲转为新风格 | [Suno Cover API](/api/cn/suno/suno_cover) | | 上传参考音频素材 | [Suno Upload API](/api/cn/suno/suno_upload) | | 分离人声与伴奏（双轨） | [Suno Stems API](/api/cn/suno/suno_stems) | | 全轨多轨分离 | [Suno Stems All API](/api/cn/suno/suno_stems_all) | | 查询异步任务状态与结果 | [Suno Fetch V2 API](/api/cn/suno/suno_fetch_v2) | | 为编曲添加人声层 | [Suno Add Vocals API](/api/cn/suno/suno_add_vocals) | | 导出高质量 WAV 格式 | [Suno WAV API](/api/cn/suno/suno_wav) | | Mashup 混搭多首歌曲 | [Suno Mashup API](/api/cn/suno/suno_mashup) | | 样本片段生成完整歌曲 | [Suno Sample to Song API](/api/cn/suno/suno_sample) | | 生成 MIDI 文件 | [Suno MIDI API](/api/cn/suno/suno_midi) | | 替换歌曲中的某一段落 | [Suno Replace Section API](/api/cn/suno/suno_replace_section) | | 裁剪已有歌曲片段 | [Suno Crop API](/api/cn/suno/suno_crop) | | 删除歌曲中的指定时间片段 | [Suno Remove Section API](/api/cn/suno/suno_remove_section) | | 为歌曲添加淡入效果 | [Suno Fade In API](/api/cn/suno/suno_fade_in) | | 为歌曲添加淡出效果 | [Suno Fade Out API](/api/cn/suno/suno_fade_out) | | 调整歌曲速度并可保持音高 | [Suno Adjust Speed API](/api/cn/suno/suno_adjust_speed) | | 拼接多段音轨 | [Suno Concatenate Track API](/api/cn/suno/suno_concat) | | 生成音效 | [Suno Sounds API](/api/cn/suno/suno_sounds) | | 对齐歌词与音频时序 | [Suno Aligned Lyrics API](/api/cn/suno/suno_aligned_lyrics) | | 生成 MV 视频 | [Suno Generate Video API](/api/cn/suno/suno_generate_video) | | 创建自定义音色 | [Suno Create Voice API](/api/cn/suno/suno_create_voice) | | BPM 分析 | [Suno BPM Analysis API](/api/cn/suno/suno_bpm) | *** ## 常见工作流 | 工作流 | 推荐路径 | | :---------- | :---------------------------------------------------------------------------------------------------------------- | | 文本提示 → 完整歌曲 | [Lyrics](/api/cn/suno/suno_lyrics)（可选）→ [Music](/api/cn/suno/suno_music) → [Fetch V2](/api/cn/suno/suno_fetch_v2) | | 参考音频 → 新生成 | [Upload](/api/cn/suno/suno_upload) → 下游接口 → [Fetch V2](/api/cn/suno/suno_fetch_v2) | | 续写优秀草稿 | [Extend](/api/cn/suno/suno_extend) → [Fetch V2](/api/cn/suno/suno_fetch_v2) | | 翻唱 / 风格重做 | [Cover](/api/cn/suno/suno_cover) → [Fetch V2](/api/cn/suno/suno_fetch_v2) | | 提取人声或伴奏 | [Stems](/api/cn/suno/suno_stems) 或 [Full Stems](/api/cn/suno/suno_stems_all) | | 混搭多首歌曲 | [Upload](/api/cn/suno/suno_upload) → [Mashup](/api/cn/suno/suno_mashup) → [Fetch V2](/api/cn/suno/suno_fetch_v2) | *** ## 轮询 vs Webhook：如何选择异步模式 大多数 Suno API 工作流都是异步的，获取结果有两种方式： **轮询 Fetch**：循环调用 `GET /suno/v2/fetch?jobId=...`，直到 `status` 变为 `SUCCESS`。上手简单，任何 HTTP 客户端均可使用，推荐调试阶段使用。建议轮询间隔 3–5 秒。 **Webhook 回调**：在生成请求中传入 `hookUrl`，任务完成后 TTAPI 主动 `POST` 结果到你的端点。后端已有公开回调地址的生产系统推荐使用。 完整的异步设计说明请参考 [Suno API 异步工作流](/grids/en/start/suno-api-async-workflow)。 *** ## 推荐首次生产接入路径 1. 阅读 [网关与鉴权](/grids/cn/development/authentication)，确保请求头和网关地址正确。 2. 完成 [Suno API Quickstart](/grids/en/start/suno-api-quickstart)，最快路径跑通集成。 3. 通过 [Suno 音乐生成 API](/api/cn/suno/suno_music) 提交生成任务。 4. 保存返回的 `jobId`，通过 [Suno Fetch V2](/api/cn/suno/suno_fetch_v2) 或 `hookUrl` 获取结果。 5. 按需追加 [Extend](/api/cn/suno/suno_extend)、[Cover](/api/cn/suno/suno_cover)、[Stems](/api/cn/suno/suno_stems) 或 [WAV 导出](/api/cn/suno/suno_wav) 等后处理步骤。 *** ## 错误码与排查 | 状态码 | 错误信息 | 说明与处理 | | :---- | :----------------------------------------------------- | :--------------------------------------- | | `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](/api/cn/suno/suno_music) 提交 `POST` 请求，带上 prompt、风格标签和模型版本（最新 Suno v5 使用 `chirp-v5`）。保存返回的 `jobId`，再通过 [Suno Fetch V2 API](/api/cn/suno/suno_fetch_v2) 或 Webhook 获取生成的音频。 ### 应该用哪个 Suno 模型？ 推荐使用 `chirp-v5-5`（Suno v5.5），它提供最高质量的人声输出、最佳曲式结构和最长的生成时长。完整的 `mv` 参数可选值请参考 [音乐 API 参考](/api/cn/suno/suno_music)。 ### `weirdnessConstraint` 参数是什么意思？ 该参数控制 AI 生成结果偏离传统音乐模式的程度。**值越高**，输出越实验性和非常规；**值越低**，结果越贴近标准曲式和流派惯例。可在提交生成请求时设置，也会出现在 Fetch 结果的每个 `musics` 条目中。 ### 如何查询任务状态？ 使用 [Suno Fetch V2 API](/api/cn/suno/suno_fetch_v2) 传入 `jobId` 轮询状态。处理中时 `status` 返回 `ON_QUEUE`；完成后 `status` 返回 `SUCCESS`，响应中包含完整的音频 URL。 ### Suno API 支持 Webhook 吗？ 支持。提交任何 Suno 任务时传入 `hookUrl` 参数，TTAPI 会在任务完成后通过 HTTP `POST` 将结果推送到你的端点，无需轮询。完整 Webhook 实现说明请参考 [Suno API 异步工作流](/grids/en/start/suno-api-async-workflow)。 ### 可以生成无人声的纯器乐吗？ 可以。在音乐生成请求中设置 `"instrumental": true`，Suno API 将生成不含任何人声的完整音轨。 ### 可以上传自己的音频作为参考吗？ 可以。使用 [Suno Upload API](/api/cn/suno/suno_upload) 上传源音频或参考素材，再将其传入下游生成接口。 ### 可以分离生成曲目中的人声和器乐吗？ 可以。使用 [Suno Stems API](/api/cn/suno/suno_stems) 进行双轨分离（人声 + 伴奏），或使用 [Suno Stems All API](/api/cn/suno/suno_stems_all) 进行全轨多轨分离。 ### 支持哪些编程语言？ TTAPI 提供标准 REST 接口，任何能发送 HTTP 请求的语言均可接入，包括 Python、Node.js、Go、Java、PHP 等。各语言接入示例请参考 [Quickstart](/grids/en/start/suno-api-quickstart)。 ### 接下来应该看哪些页面？ 从 [Suno API Quickstart](/grids/en/start/suno-api-quickstart) 开始，再深入 [音乐生成 API](/api/cn/suno/suno_music) 和 [Fetch V2 API](/api/cn/suno/suno_fetch_v2) 掌握核心的生成与查询流程。如需了解异步设计决策，阅读 [Suno API 异步工作流](/grids/en/start/suno-api-async-workflow)。 ***