> ## 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.

> ## Agent Instructions
> Send API requests to https://api.ttapi.io with the TT-API-KEY header. Midjourney account hosting uses https://hold.ttapi.io. Claude Code uses https://cc.ttapi.io.
> Most generation endpoints are asynchronous. The submit response returns a job id. Poll that product's fetch endpoint, or pass a webhook on the submit request. A fetch call does not start a new generation.
> 1 USD = 100 quota. Check the pricing page for that product before estimating cost.
> This file lists the English docs. Follow every /_llms/ link recursively for the API reference, Chinese, and Russian. Open a page's .md URL for the endpoint schema.

# Suno API 快速开始

> 快速上手 TTAPI 的 Suno API，包含鉴权、首次请求流程、异步轮询、Webhook 回调及生产环境最佳实践。

# Suno API 快速开始

本指南帮助你以最短路径完成 **Suno API** 集成。适合希望从 API Key 直接走到第一首歌曲完成的团队。

完整接口文档请参考 [Suno API 文档总览](/api/cn/suno)。

## 本指南包含

* 获取 `TT-API-KEY`
* 选择合适的首个接口
* 创建歌词或直接生成音乐
* 查询异步结果
* 通过翻唱、延伸、词曲分离等接口继续工作流

## 1. 准备账号

在调用 Suno 接口之前，请确认：

* 已获取有效的 `TT-API-KEY`
* 已了解 [网关与鉴权](/grids/cn/development/authentication)
* 已查看 [音频定价](/grids/cn/start/pricing/audio) 确认额度充足

标准网关调用模式：

* Base URL：`https://api.ttapi.io`
* Header：`TT-API-KEY`
* 响应流程：提交请求 -> 保存 `data.jobId` -> 查询结果或等待 `hookUrl` 回调

## 2. 选择起始接口

| 场景 | 推荐起始接口 |
| :- | :- |
| 只有提示词或创意 | [Suno 生成音乐](/api/cn/suno/suno_music) |
| 需要先写歌词 | [Suno 生成歌词](/api/cn/suno/suno_lyrics) |
| 已有参考音频 | [Suno 上传音频](/api/cn/suno/suno_upload) |
| 复用已有歌曲结构 | [Suno 延伸](/api/cn/suno/suno_extend) 或 [Suno 翻唱](/api/cn/suno/suno_cover) |

## 3. 提交首次生成请求

最常见的集成从 [Suno 生成音乐](/api/cn/suno/suno_music) 开始：

```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-v6",
    "title": "Midnight Drive",
    "tags": "synthwave, female vocal, cinematic",
    "prompt": "[Verse] Neon headlights on a rainy street"
  }'
```

请求被接受后，返回：

```json theme={null}
{
  "status": "SUCCESS",
  "message": "success",
  "data": {
    "jobId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

请立即保存 `data.jobId`，后续调用 [Fetch V2](/api/cn/suno/suno_fetch_v2) 时需要使用。

## 4. 使用 jobId 查询结果

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

Fetch 接口可能返回 `ON_QUEUE`、`SUCCESS` 或 `FAILED`。成功时的响应结构包含 `musics` 数组，其中有 `musicId`、`audioUrl`、`videoUrl` 等字段。

## 5. 轮询与 Webhook 的选择

* **轮询**：通过 [Fetch V2](/api/cn/suno/suno_fetch_v2) 定期查询任务状态，适合首次集成
* **Webhook**：提交时传入 `hookUrl`，任务完成后自动回调，适合已有稳定后端的项目

如需设计任务队列或 Webhook 处理逻辑，请参考 [Suno 异步工作流指南](/grids/cn/start/suno-api-async-workflow)。

## 6. 常用后续接口

首个流程跑通后，通常会接入以下接口：

* [Suno 延伸](/api/cn/suno/suno_extend) — 延续优秀创意
* [Suno 翻唱](/api/cn/suno/suno_cover) — 对已有歌曲重新演绎
* [Suno 词曲分离](/api/cn/suno/suno_stems) — 分离人声与伴奏
* [Suno 上传音频](/api/cn/suno/suno_upload) — 从已有音频开始
* [Suno 文件下载](/api/cn/suno/suno_download) — 下载高质量文件

## 常见集成错误

* 没有根据实际素材选择正确的起始接口
* 将异步任务当作同步请求处理
* 忘记保存 `data.jobId`
* 需要更详细的分离时误用了 [Stems](/api/cn/suno/suno_stems)，应使用 [全轨道 Stems](/api/cn/suno/suno_stems_all)
* 在高成本接口启用前未查看定价

## 相关页面

* [Suno API 文档总览](/api/cn/suno)
* [Suno 生成音乐](/api/cn/suno/suno_music)
* [Suno Fetch V2](/api/cn/suno/suno_fetch_v2)
* [音频定价](/grids/cn/start/pricing/audio)
* [Suno 工作流指南](/grids/cn/start/suno-api-workflows)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.