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 返回兩個局部替換候選。兩個操作都不會自動選擇藝術結果。模型必須使用公開名稱：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 以供排查。