> ## 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 API guide - 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 音声 URL からプロジェクトに追加可能な素材を初期化 |
| `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.example.com/reference.mp3",
  "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` は 2 つの部分置換候補を返します。どちらの操作も、芸術的な結果を自動選択しません。モデルには公開名を使用する必要があります：`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.