Skip to main content
POST
POST /v1/music/generations runs every Suno and Flow Music model. Each model ID is one operation, such as generating a song, writing lyrics, extending a track, or splitting stems, and the body fields depend on that model. Every request becomes an asynchronous task: submit it, keep the task id, and read the result from GET /v1/tasks/{id}. Follow-up operations take one of your earlier tasks as their source, so you can chain steps: generate a song, extend it, join the parts, then export or split it. Open a model’s page under Audio Series > Suno or Audio Series > Flow Music for its exact fields and an example.

Models

Suno

Flow Music

Flow Music runs Google Lyria. Each task returns one clip.

Request body

Send a JSON body with model, the fields that model defines, and optional webhook fields. The body is validated strictly against the model’s contract: a field the model doesn’t list returns invalid_music_request. These fields are shared by several models:
string
required
A Suno or Flow Music model ID from the tables above.
string
Follow-up operations: the id of your earlier task that holds the source track, such as task_2f8KcX1mQpR7vT0yZa9Lb3. See Reference earlier tasks.
integer
default:"1"
The 1-based position of the source track in that task’s result.tracks, from 1 to 8.
string[]
suno-mashup only: exactly two source task IDs.
integer[]
suno-mashup only: the track position in each source task, in the same order. Defaults to [1, 1].
string
The id of a succeeded suno-persona task, to sing with that Persona. Can’t be combined with custom_model_task_id.
string
The id of a succeeded suno-custom-model task, to generate with that model. Replaces version, so don’t send both.
boolean
default:"false"
Suno Max mode, on the models whose price lists it. Bills twice the request price and needs custom mode where the model has a custom field.
string
Optional public https URL that receives one signed event when the task reaches a final state. See Task webhooks.
string
Required with webhook: 16 to 256 characters, used to sign the delivery.
string
Optional, 1 to 200 characters. Resending the same body with the same key returns the original task instead of starting a second, billed one.

Suno modes

suno-music and the Suno models that write new music from a source, such as suno-extend, suno-cover, and suno-mashup, have a custom field. Each model page says whether it has one.
  • Custom mode (custom: true): prompt holds your lyrics, and the style fields apply: style on suno-music or tags on the other models, plus title and negative_tags.
  • Description mode (custom: false): the model writes the song from a description. suno-music reads the description from prompt; the other models read it from gpt_description, which is then required.
On models with a custom field, max_mode and the target duration need custom mode. max_mode: true bills twice the request price. variety is unrelated: variety: "max" doesn’t turn on Max mode or change the price. Send version (v6, v6-wild, or v6-mini; default v6) or custom_model_task_id, not both.

Submit a task

A valid request returns HTTP 202 with a task object whose status is queued. The Location header holds /v1/tasks/{id} and x-gateway-task-id holds the task ID. The gateway reserves the request price at submission.

Read the result

Poll GET /v1/tasks/{id} every 10 to 20 seconds until status is succeeded or failed, or pass webhook to be notified instead. The task passes through queued and processing; progress shows 0 to 100 when the provider reports it. modality is audio. When the task succeeds, result holds the normalized output. Which fields appear depends on the model; each model page shows its result.
string[]
Every delivered media URL, primary output first. Empty for text-only results such as lyrics or BPM.
object[]
Tracks in their original order. Follow-up operations select a track by its index.
object[]
suno-lyrics and flow-music-lyrics: entries with text and, when returned, title and tags.
object[]
suno-download: one format and url per requested format.
string[]
suno-mp4 and flow-music-video: MP4 URLs.
string
suno-style-boost: the expanded style tags.
object
suno-persona: the Persona id. Reuse it through persona_task_id.
object
suno-custom-model: the model id and name. Reuse it through custom_model_task_id.
object
suno-bpm: average, and min and max when reported.
object[]
suno-timed-lyrics: entries with text, start_s, end_s, and success.
object
suno-midi: state and instruments[], each with a name and notes[] (pitch, start, end, velocity).
object
suno-voice: the voice details the provider returns, as flat key-value pairs.
Result URLs are kept for about 72 hours. Download the files you want to keep to your own storage. For convenience, GET /v1/tasks/{id}/content redirects to the first URL in result.urls.

Reference earlier tasks

Follow-up operations never take provider IDs or file URLs of earlier results. You pass the SnapGen task ID of an earlier task, and the gateway resolves it: Before it reserves any balance, the gateway checks that each referenced task:
  1. Is yours. A task from another account is treated as missing: source_task_not_found (HTTP 404).
  2. Has succeeded. A task that is still running, or that failed, returns source_task_not_ready (HTTP 409). Wait for a running task to succeed, then retry; a failed task can’t be a source.
  3. Came from a compatible model. Each model page lists the models it accepts as a source under Source tracks. For example, suno-concat takes only suno-extend and suno-upload-extend results, and suno-add-vocals takes only suno-upload results. Otherwise: source_task_incompatible (HTTP 400).
  4. Has the track you picked. An index beyond the source’s tracks returns source_index_out_of_range (HTTP 400), with a message that says how many tracks the source has.
The follow-up then runs on the same provider account as its source, and the gateway substitutes the provider’s own task and track IDs for you. Suno models reference Suno tasks, and Flow Music models reference Flow Music tasks. To use your own audio as a source, import it first with suno-upload or flow-music-upload.

Workflow: generate, extend, and join

This example generates a song from lyrics, extends its first track from second 60, then joins the extension and the original into one full-length track. Each step waits for the previous task to succeed and passes its task ID forward.
1

Generate the song

Save the returned id, for example task_2f8KcX1mQpR7vT0yZa9Lb3, and poll it until status is succeeded. Pick a track from result.tracks; its index is the source_index for the next step.
2

Extend a track

continue_at must be inside the source track. Poll the new task, for example task_7hQmN2pX5rT8vW1yZc4Kd6, until it succeeds.
3

Join the parts

When this task succeeds, result.urls[0] is the full song. Download it within about 72 hours, or export other formats with suno-download.
The same chain as a script:

Billing

Each music model bills a fixed price per request, listed in the tables above. Where the price lists a Max mode rate, max_mode: true bills twice the normal price. The gateway reserves the price at submission and settles it when the task succeeds. Failed tasks release the reservation and aren’t charged, and polling is free. A chained workflow bills each step: the example above costs $0.075 + $0.075 + $0.006 = $0.156.

Errors

A task that fails at the provider reports status: "failed" with error.code provider_task_failed. See Errors for rate limits and other failures.