POST https://api.acedata.cloud/suno/projects is the Beta API for managing multitrack projects. Use action to distinguish between creating, saving, generating candidates, committing candidates, and exporting.
retrieve, every operation requires Idempotency-Key. The same key with the same request only returns the original result; the same key with a different request returns 409. When a paid generation encounters a network timeout or an uncertain submission result, first query using the original task ID or the same idempotency key; do not directly resend with a different key.
Identifiers and Time Units
start_seconds / end_seconds are seconds within the source audio; start_beats / end_beats are beats on the project timeline. state.timing.bps is beats per second, with a default of 2. For example, a 41-second clip starting at beat 0 has a default endpoint of beat 82. The seconds range for generate_track is used to specify the generation reference and does not guarantee that a candidate will only have the length of that range.
Operation Flow
If only performing a partial replacement, an existing usable source audio is sufficient, and
render is not required first; if the source audio is already in the project, upload and add_track can also be skipped. render_audio_id is only the required reference for generate_track.
When an asynchronous operation is submitted, it first returns { "task_id": "...", "trace_id": "..." }, which does not indicate successful generation. Poll:
finished_at and its response.success is true; when response.success=false, read response.error. Although save may include task_id, it completes synchronously within this API. upload, render, generate_track, and replace_section do not modify the project version; after save, add_track, commit_candidate, and remove_track succeed, the new version_id should be obtained.
Request Conventions
The following examples demonstrate the passing of IDs and versions between operations. Responses only list fields related to the current step; during integration, replace the example IDs with response values from the current application.

