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