action により操作タイプが決まります。Project の主キーには一律で id を使用します。version_id は現在のプロジェクトバージョンを表し、すべての変更およびエクスポート操作では、並行更新による上書きを避けるため最新バージョンを送信する必要があります。
操作概要
非同期操作は直ちに
task_id を返します。無料の /suno/tasks インターフェースを使用してポーリングするか、callback_url を渡して終端状態の結果を受信します。
作成と読み取り
Idempotency-Key Header を送信する必要があります。作成成功後、レスポンス内の data.id が Project ID です。新規の空プロジェクトには、初回保存前は version_id がない場合があります。
state が含まれます。新規の空プロジェクトは {"tracks":[],"timing":{"bps":2}} を返し、そのまま初回保存に使用できます。timing.bps は毎秒の拍数を表し、デフォルトは 2（120 BPM）で、正の数でなければなりません。クリップの startBeats、endBeats、および readStartBeats はプロジェクトの拍単位を使用するため、音声分析内の小節位置を直接タイムライン座標として扱うことはできません。
完全な状態の保存
version_id を省略できます。初回保存でバージョンが生成された後、以降の保存では最新の値を送信する必要があります。バージョンが変更されている場合、インターフェースは HTTP 409 を返します。この場合は再度 retrieve を実行し、変更をマージしてから新しい冪等キーで送信してください。古いリクエストを無闇に再試行しないでください。
アップロードとトラック追加
response.data.candidate.audio_id から音声 ID を取得します。次に、それをプロジェクトへ追加します：
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 を返します。別のモデルへ自動的に切り替わることはありません。
generate_track ではさらに、render_audio_id（完了済みのプロジェクトエクスポート音声）、stem_control_tags、および元音声の source_audio_id を指定する必要があります。batch_size は 1～4 で、デフォルトは 2 です。start_seconds、end_seconds は元音声の秒数です。fixed=true の置換区間は 26 秒未満でなければなりません。
候補を選択した後にコミットします：
start_beats、end_beats を渡さないでください。新規トラック候補は事前に保存した空のトラックにコミットする必要があり、デフォルトでは元クリップの開始位置を引き継ぐか、重複しない範囲を明示的に渡します。同一トラック上で既存クリップが重複している場合は 400 が返されます。先に生成してから新しいトラックを作成しないでください。バージョンの変更により候補が期限切れになります。
完全な楽曲のエクスポート
start_beats、end_beats を省略した場合、デフォルトではすべての可聴クリップの最も早い開始位置から最も遅い終了位置までをエクスポートします。ミュートされたトラック／クリップは含まれず、solo トラックが存在する場合は solo トラックのみが選択されます。空のプロジェクトまたは有効な可聴トラックがない場合は 400 が返されます。終端状態の結果には、render_id、audio_id、audio_url、および長さが含まれます。プロジェクトは作成時の実行環境に紐付けられており、環境間で移行したり自動フェイルオーバーしたりすることはできません。
合法的な利用権を所有する音声のみをアップロードまたは処理できます。プロジェクト API は現在 Beta です。重要な結果に含まれる最終音声 URL は永続化してください。
ポーリングと障害復旧
/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 を保持してください。