How to Build a Version-Safe Music Project Workflow with the Suno Studio Projects API

Multi-track audio tools become hard to integrate once several edits, generated candidates, and exports are happening at the same time. The Suno Studio project API gives builders a single project-oriented workflow, but the important part is not just calling an endpoint: it is keeping project state and version_id handling disciplined.

What you can do

The API manages multi-track music projects through one endpoint: POST /suno/projects. Each request supplies an action that determines the operation. This design supports project creation, state retrieval and saving, audio upload, track additions, generation, section replacement, candidate commits, track removal, and final rendering.

A reliable integration should treat the project state and its version as the source of truth. The project primary key is always id. The version_id identifies the current project version. Modification and export requests must use the latest version so that concurrent changes do not overwrite one another.

How it works

The API separates immediate project operations from operations that create background work. The synchronous actions are create, retrieve, save, and remove_track. The asynchronous actions are upload, add_track, generate_track, replace_section, commit_candidate, and render.

An asynchronous operation returns a task_id immediately. Poll the free /suno/tasks endpoint to observe task completion, or provide a callback_url when the action supports receiving final-state results through a callback. Your application should not assume an async action has completed merely because the initial request succeeded.

Create the project and establish its identity

Create an empty project by sending the create action with a title:

{
  "action": "create",
  "title": "My Studio Project"
}

The successful response returns the Project ID in data.id. Store this value because all later requests use it as id. A newly created empty project may not have a version_id before its first save. This is an important distinction: do not require a version ID immediately after creation when no state has been saved yet.

All modification operations should include a unique Idempotency-Key request header. Use a different key when you intentionally submit a new modification request. In particular, a conflict recovery attempt must use a new idempotency key rather than reusing the request that conflicted.

Retrieve before changing state

Read a project with retrieve:

{
  "action": "retrieve",
  "id": "PROJECT_ID"
}

The retrieve response contains the complete editable state. Retrieve the project before modifying it, then base your changes on the values returned by the API. Do not manually construct internal timing and track structures from scratch. This approach ensures that a save operation preserves the state representation returned by the service.

For workflows involving multiple edits, keep track of the latest project version returned by the relevant result. Every time the project changes, subsequent modifications should use the updated version_id.

Save complete project state with optimistic version handling

The save action persists the complete project state. A representative request is:

{
  "action": "save",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "title": "Edited Project",
  "state": {
    "tracks": [],
    "timing": {}
  }
}

The first save for a new empty project may omit version_id. After that first save produces a version, every later save must send the latest value. If the version is no longer current, the API returns HTTP 409.

Handle HTTP 409 as a merge workflow, not as a retry condition. Retrieve the project again, merge your intended changes with the newly returned state, and submit the resulting complete state using the current version ID and a new idempotency key. Do not blindly retry the earlier save request, because it was built from an outdated version.

Upload audio and add it as a track

To use audio from an HTTPS URL, first initialize it through the asynchronous upload action:

{
  "action": "upload",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "audio_url": "https://cdn.example.com/reference.mp3",
  "async": true
}

When the upload task completes, its result includes a candidate audio_id. Use that identifier with add_track to add the audio to the project:

{
  "action": "add_track",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "audio_id": "AUDIO_ID",
  "name": "Backing Vocals"
}

Because these steps are version-sensitive, use the latest project version when issuing the add request. Only upload or process audio for which you have legal usage rights.

Generate, review, and commit candidates

The generation actions produce candidates rather than automatically applying an artistic choice. generate_track creates track candidates for a project range. replace_section creates two local replacement candidates. For example, a replacement request specifies source audio and an exact time range:

{
  "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": "new lyric segment",
  "async": true
}

After reviewing the result, commit the selected candidate with commit_candidate, providing the originating operation_id, the selected candidate_id, and the destination track_id. Candidates are bound to the project version that existed at generation time. If the project changed after generation, older candidates cannot be committed directly.

Render the saved version and persist output details

Use render to export a complete song from a saved project version. The server reads the authoritative state for the specified version and assembles the export parameters:

{
  "action": "render",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "title": "Final Mix",
  "lyrics": "[Instrumental]",
  "async": true,
  "callback_url": "https://example.com/webhooks/suno"
}

The final-state result contains render_id, audio_id, audio_url, and duration. Persist the final audio URL for important results. Projects are bound to the execution environment in which they are created; they cannot be migrated across environments or automatically fail over.

If you are building an editor, internal tool, or automated production workflow, the practical pattern is simple: retrieve, modify the returned state, save with the current version_id, resolve conflicts by retrieving again, and only render from a saved version. Read the full Suno Studio Projects Integration Guide for the source request shapes and operation list.