> ## 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、Fetch 接口、重试机制及生产级异步工作流模式。

# Suno API 异步工作流

大多数生产级 **Suno API** 集成都是异步的。你的应用提交任务后获得 `jobId`，再通过轮询或 Webhook 获取最终结果。

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

## 何时需要异步

以下场景需要使用异步模式：

* 生成完整歌曲或较长音频
* 上传参考音频后进行后续处理
* 需要在后端或队列中可靠处理
* 不希望阻塞用户请求等待音频生成完成

## 核心流程

1. 通过 [Suno 生成音乐](/api/cn/suno/suno_music)、[上传音频](/api/cn/suno/suno_upload)、[翻唱](/api/cn/suno/suno_cover) 或 [延伸](/api/cn/suno/suno_extend) 提交任务
2. 将返回的 `jobId` 存入数据库或队列
3. 通过 [Suno Fetch V2](/api/cn/suno/suno_fetch_v2) 或 `hookUrl` 获取最终结果
4. 在任务到达终态后才更新应用状态

## 轮询 vs Webhook

| 方式 | 适用场景 | 说明 |
| :- | :- | :- |
| [Fetch V2](/api/cn/suno/suno_fetch_v2) 轮询 | 希望简单实现或客户端控制刷新 | 易于调试和重放 |
| `hookUrl` 回调 | 已有公网后端，希望推送式更新 | 减少重复请求 |

## 推荐轮询的场景

* 正在构建第一个集成版本
* 希望在日志中观察任务状态变化
* 需要手动重试失败的查询
* 应用已有定时任务或 Worker 系统

## 推荐 Webhook 的场景

* 需要即时的后台完成通知
* 每天处理大量任务
* 希望减少重复请求流量
* 后端可以暴露稳定的公网端点

## 推荐实现细节

* 将 `jobId`、请求类型和提交时间一起持久化
* 将任务查询视为幂等操作，确保重试安全
* 保持接口类型与结果结构的清晰映射
* 记录 Webhook 投递和 Fetch 响应日志以便调试
* 保留回退路径，即使 Webhook 失败也能查询 [Fetch V2](/api/cn/suno/suno_fetch_v2)

## 常见失败模式

* Webhook URL 无法公网访问
* 应用过早丢弃了 `jobId`
* 前端期望提交接口直接返回最终音频
* 混用了旧版 [Fetch](/api/cn/suno/suno_fetch) 和 [Fetch V2](/api/cn/suno/suno_fetch_v2)
* 长时间运行的任务缺少重试或超时逻辑

## 相关页面

* [Suno API 文档总览](/api/cn/suno)
* [Suno Fetch V2](/api/cn/suno/suno_fetch_v2)
* [Suno 上传音频](/api/cn/suno/suno_upload)
* [Suno 生成音乐](/api/cn/suno/suno_music)
* [网关与鉴权](/grids/cn/development/authentication)


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