A Practical Guide to Building Version-Safe Music Workflows with the Suno Studio Projects API

If you have ever tried to turn generated music into an editable product feature, you know the hard part is not only creating audio. The hard part is keeping project state, track edits, replacements, and final exports coordinated without overwriting someone else's work.

The Suno Studio Projects API solves that problem with a single project-oriented endpoint. Instead of treating every music generation as a one-off file, you work with a project, retrieve its editable state, save complete versions, add or generate tracks, commit selected candidates, and render the final song when the mix is ready.

What you can do

The project API is centered on one endpoint:

POST /suno/projects
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

The operation is selected with an action field. The documented actions cover the full lifecycle of a multi-track project:

create: create an empty project.
retrieve: read the project and its complete editable state.
save: save the complete project state.
upload: initialize assets from an HTTPS audio URL so they can be added to a project.
add_track: add existing audio to the project.
generate_track: generate track candidates for a specified range.
replace_section: generate local replacement candidates.
commit_candidate: commit the selected candidate to the project.
remove_track: delete a specified track.
render: export the saved version as a complete song.

This shape is useful for builders creating music editors, remix tools, collaborative production flows, or backend pipelines that need to preserve every edit as a versioned project rather than a loose collection of audio URLs.

How it works

Every request goes to /suno/projects, but the action changes what the server does. The Project primary key is id. The current version is represented by version_id. For modification and export operations, you should send the latest version_id to avoid concurrent overwrites.

Some actions are synchronous and return immediately. Others are asynchronous and return a task_id. For async actions, poll /suno/tasks or provide a callback_url to receive final-state results. That means your application should treat project editing as a small workflow: submit the project operation, store the task id when present, wait for completion, then retrieve or save the next authoritative project state.

Create first, then retrieve state

A new project starts with a simple create request:

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

After creation, the response contains data.id, which is the Project ID. A newly created empty project may not have a version_id before its first save. For modification operations, the documentation recommends sending a unique Idempotency-Key header.

Before you edit, retrieve the project:

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

The retrieve response contains the complete state. In practice, this is the safest way to build your UI or automation: retrieve first, make changes against the returned data, and save the complete state back. Avoid constructing internal timing and track structures from scratch unless your application is already working from a previously retrieved state.

Save with version checks instead of blind retries

Saving is a complete-state operation:

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

The first save of a new empty project may omit version_id. After the first version exists, subsequent saves must submit the latest version_id. If the version has changed, the API returns HTTP 409. That response is not a signal to retry the same payload. It is a signal to retrieve again, merge your local changes with the new state, and submit with a new idempotency key.

This is the most important builder detail in the API: treat version_id as your guardrail for collaborative or automated editing. It prevents a background process, a user edit, or another worker from silently overwriting the project.

Add audio, replace a section, then commit a candidate

To bring external audio into a project, first upload from an HTTPS audio URL:

{
  "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, the task result returns a candidate audio_id. Add that audio as a track:

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

For localized editing, replace_section generates two replacement candidates for a time range. The operation does not automatically pick an artistic result; your application should present candidates or apply its own selection logic.

{
  "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 selecting a candidate, commit it:

{
  "action": "commit_candidate",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "operation_id": "OPERATION_ID",
  "candidate_id": "CANDIDATE_ID",
  "track_id": "TRACK_ID"
}

Candidates are bound to the project version that existed when they were generated. If the project has already changed, old candidates cannot be committed directly, so retrieve the current state before trying to continue the workflow.

Render the final mix

When the saved project version is ready, export it with render:

{
  "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 server reads the authoritative project state for the specified version and assembles the export parameters. The final-state result contains render_id, audio_id, audio_url, and duration. Persist the final audio_url for important results, because it is the artifact your product will likely show, store, or hand off to downstream systems.

One final operational note: projects are bound to the execution environment at creation and cannot be migrated across environments or automatically fail over. Also, only upload or process audio for which you have legal usage rights.

Where to go next

If you are building a music workflow, model your backend around three rules: retrieve before modifying, save with the latest version_id, and treat async operations as task-driven workflows. That keeps the product predictable even as users add tracks, regenerate sections, and export final mixes.

Read the source documentation here: Suno Studio Projects Integration Guide.

Search This Blog

AceDataCloud