> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno Studio 项目接入指南

> Suno Music Generation 集成指南 - Ace Data Cloud

Suno Studio 项目 API 通过一个入口管理多轨音乐工程：

```http theme={null}
POST /suno/projects
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

请求中的 `action` 决定操作类型。Project 主键统一使用 `id`；`version_id` 表示当前工程版本，所有修改和导出操作都必须提交最新版本，避免并发覆盖。

## 操作概览

| action | 模式 | 用途 |
| - | - | - |
| `create` | 同步 | 创建空工程 |
| `retrieve` | 同步 | 读取工程及完整可编辑 `state` |
| `save` | 同步 | 保存完整工程状态 |
| `upload` | 异步 | 从 HTTPS 音频地址初始化可加入工程的素材 |
| `add_track` | 异步 | 将已有音频加入工程 |
| `generate_track` | 异步 | 为指定区间生成新音轨候选 |
| `replace_section` | 异步 | 生成局部替换候选 |
| `commit_candidate` | 异步 | 将选中的候选提交到工程 |
| `remove_track` | 同步 | 删除指定轨道 |
| `render` | 异步 | 将已保存版本导出为完整歌曲 |

异步操作立即返回 `task_id`。使用免费的 `/suno/tasks` 接口轮询，或传入 `callback_url` 接收终态结果。

## 创建和读取

```json theme={null}
{
  "action": "create",
  "title": "My Studio Project"
}
```

所有修改操作应发送唯一的 `Idempotency-Key` Header。创建成功后响应中的 `data.id` 是 Project ID。新建空工程在首次保存前可能没有 `version_id`。

```json theme={null}
{
  "action": "retrieve",
  "id": "PROJECT_ID"
}
```

读取响应包含完整 `state`。新建空工程返回 `{"tracks":[],"timing":{"bps":2}}`，可直接用于首次保存。`timing.bps` 表示每秒拍数，默认 2（120 BPM），必须为正数；片段的 `startBeats`、`endBeats` 和 `readStartBeats` 使用工程拍单位，不能把音频分析中的小节位置直接当成时间轴坐标。

## 保存完整状态

```json theme={null}
{
  "action": "save",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "title": "Edited Project",
  "state": {
    "tracks": [],
    "timing": {
      "bps": 2
    }
  }
}
```

新建空工程的首次保存可省略 `version_id`；首次保存生成版本后，后续保存必须提交最新值。如果版本已变化，接口返回 HTTP 409。此时重新 `retrieve`，合并修改后再用新的幂等键提交；不要盲目重试旧请求。

## 上传和添加轨道

```json theme={null}
{
  "action": "upload",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3?example=audio-001",
  "async": true
}
```

上传成功后，从 `response.data.candidate.audio_id` 读取音频 ID。再将其加入工程：

```json theme={null}
{
  "action": "add_track",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "audio_id": "AUDIO_ID",
  "name": "Backing Vocals"
}
```

添加轨道默认保留音频播放速度，并根据工程 `timing.bps` 把音频时长转换为拍数。每次 `save`、`add_track`、`commit_candidate` 或 `remove_track` 后，都应使用响应中的新 `version_id`。

## 生成和替换

`generate_track` 为工程区间生成音轨候选；`replace_section` 返回两个局部替换候选。两个操作都不会自动选择艺术结果。模型必须使用公开名称：`chirp-v3-5`、`chirp-v4`、`chirp-v4-5`、`chirp-v4-5-plus`、`chirp-v5`、`chirp-v5-5`、`chirp-v6`、`chirp-v6-wild` 或 `chirp-v6-mini`；具体操作的可用性仍以任务终态为准，不支持的名称会在提交前返回 400。不会自动改用另一模型。

```json theme={null}
{
  "action": "replace_section",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "source_audio_id": "AUDIO_ID",
  "start_seconds": 35.12,
  "end_seconds": 48.76,
  "model": "chirp-v6",
  "replacement_lyrics": "新的歌词片段",
  "async": true
}
```

`generate_track` 还必须提供 `render_audio_id`（已完成的工程导出音频）、`stem_control_tags` 和源音频 `source_audio_id`。`batch_size` 为 1–4，默认为 2；`start_seconds`、`end_seconds` 是源音频秒数。`fixed=true` 的替换区间必须短于 26 秒。

选择候选后提交：

```json theme={null}
{
  "action":"commit_candidate",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "operation_id":"OPERATION_ID",
  "candidate_id":"CANDIDATE_ID",
  "track_id":"TRACK_ID"
}
```

候选与生成时的工程版本绑定。工程已经变化时，旧候选不能直接提交。

局部替换候选提交到包含唯一源片段的原轨道，完整 take 候选保留原位置并替换原片段；区间候选仅替换请求区间，保留前后片段。无法可靠匹配时长时返回 400 并保留原工程；此时不要传 `start_beats`、`end_beats`。新轨候选应提交到提前保存的空轨道，默认沿用源片段起点，或显式传入无重叠范围；同一轨道上已有片段重叠会返回 400。不要先生成再新建轨道，否则版本变化会使候选过期。

## 导出完整歌曲

```json theme={null}
{
  "action": "render",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "title": "Final Mix",
  "lyrics": "[Instrumental]",
  "async": true,
  "callback_url": "https://example.com/webhooks/suno"
}
```

服务端读取指定版本的权威工程状态并组装导出参数。省略 `start_beats`、`end_beats` 时，默认导出所有可听片段的最早起点到最晚终点；静音轨道/片段不参与，solo 轨道存在时仅选择 solo 轨道。空工程或无有效可听轨道返回 400。终态结果包含 `render_id`、`audio_id`、`audio_url` 和时长。项目绑定创建时的执行环境，不能跨环境迁移或自动故障切换。

> 仅可上传或处理您拥有合法使用权的音频。工程 API 当前为 Beta；请持久化重要结果中的最终音频 URL。

## 轮询与失败恢复

```json theme={null}
{
  "action": "retrieve",
  "id": "TASK_ID"
}
```

把上面的请求发送到 `/suno/tasks`。Projects 任务以 `finished_at` 存在且 `response.success=true` 表示成功；`response.success=false` 表示失败。提交返回 HTTP 200 或 `task_id` 只代表已受理，不代表音频完成。

同一个 `Idempotency-Key` 与相同请求会回读原结果（包括失败），不会自动重新生成或重复扣费。想显式重试一个已失败的操作时，先查询原任务确认失败，再使用新键；不要在原任务仍处理中或结果不确定时重新提交。

错误分类包括 `studio_unavailable` / `studio_model_unavailable`（503，暂时无法处理或模型不可用）、`studio_model_unsupported`（400，模型不支持该操作）、`studio_state_invalid`（400，工程状态或导出范围无效）、`too_many_requests`（429）、`studio_audio_unavailable`（403，引用音频不能用于工程导出）和 `content_rejected`（403）。保留 `trace_id` 用于排查。


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