POST https://api.acedata.cloud/suno/projects 是管理多軌工程的 Beta 介面。透過 action 區分建立、儲存、生成候選、提交候選和匯出。
retrieve 外,每次操作都需要 Idempotency-Key。相同鍵和相同請求只會回傳原結果;相同鍵搭配不同請求會回傳 409。收費生成遇到網路逾時或提交結果不確定時,先使用原任務 ID 或相同冪等鍵查詢,不能直接換鍵重送。
識別碼和時間單位
start_seconds / end_seconds 是來源音訊內的秒數;start_beats / end_beats 是工程時間軸上的拍數。state.timing.bps 是每秒拍數,預設為 2。例如 41 秒的片段從第 0 拍開始,預設終點為第 82 拍。generate_track 的秒數區間用於指定生成參考,不保證候選只有該區間的長度。
操作流程
如果只做局部替換,既有可用來源音訊即可,不需要先
render;如果來源音訊已在工程中,也可跳過 upload 和 add_track。render_audio_id 僅是 generate_track 的必填參考。
非同步操作提交時會先回傳 { "task_id": "...", "trace_id": "..." },不表示生成成功。輪詢:
finished_at,且其中的 response.success 為 true,才算成功;response.success=false 時讀取 response.error。save 雖可能帶有 task_id,但它在本介面內同步完成。upload、render、generate_track、replace_section 不修改工程版本;save、add_track、commit_candidate、remove_track 成功後應取得新的 version_id。
請求約定
下列範例串聯展示各操作之間的 ID 和版本傳遞。回應只列出與目前步驟有關的欄位;接入時請以目前應用程式的回應值取代範例 ID。

