Suno API Overview

Call Suno through the API: generate songs and lyrics, rework, extend, split into stems, export, and clone voices. Each action is its own endpoint, POST /suno/v2/{action}, and every action is an asynchronous task: you get a task ID on submission, then fetch the result, or pass notify_hook and wait for us to push it.

Basics

Item	Value
Base URL	`https://api.ephone.ai`
Authentication	Header `Authorization: Bearer YOUR_API_KEY`
Request body	JSON, `Content-Type: application/json`

Every endpoint page has a playground on the right: enter your API key and parameters to send a request. Playground requests are real and billed as usual.

Call flow

Submit a task

Call the endpoint for the action, for example Music Generation. data.task_id in the response is the task ID.

Get the result

Poll Get Task every 3 to 5 seconds until status becomes SUCCESS or FAILURE; use Batch Get Tasks for several at once. Or pass notify_hook on submission and we POST the same content as the fetch result when the task ends.

Keep creating

music_id in the result is how follow-up actions such as extend, cover, stems and export find the track. Store it with the task.

Every action returns the same submit response, and fetch responses share one outer structure; where the outputs live is described in the Task result section of each endpoint page.

You can also submit through the unified task endpoint POST /v1/task/submit with model set to suno/ plus the action name (for example suno/music) and the parameters inside input. Both behave and bill the same.

Every endpoint

Each action lives at POST /suno/v2/{action}; action names are in the first column of each table.

Create something new

Endpoint	What it does
Music Generation `music`	Generate a full song from a one-line idea or your own lyrics. Returns two takes.
Lyric Writing `lyrics`	Write lyrics from a theme. Returns two drafts.
Sound Effects `sounds`	Generate one-shot or looping sound effects, with optional BPM and key.
Reference Generation `inspo`	Create from one to four reference tracks as style guides.
Sample Rework `sample`	Chop a sample and build a new track around it.
Mashup `mashup`	Blend two tracks into a new one.

Work on an existing track

Endpoint	What it does
Extension `extend`	Continue a track from a given second, keeping the original style.
Cover `cover`	Re-perform a track in a new style while keeping its melodic skeleton.
Remaster `remaster`	Re-render a track while keeping its structure.
Section Rewrite `replace-section`	Rewrite just one time range, leaving the rest untouched.
Add Vocals `add-vocals`	Add a sung vocal line over an instrumental.
Add Instrumental `add-instrumental`	Build a full instrumental around a vocal track.
Stem Layering `add-stem`	Layer an additional instrument track onto an existing song.

Bring your own audio

Endpoint	What it does
Audio Upload `upload`	Upload audio so other actions can reference it.
Upload & Cover `upload-cover`	Upload your own audio and re-perform it in a new style.
Upload & Extend `upload-extend`	Upload your own audio and continue it from a given point.

Split and reassemble

Endpoint	What it does
Vocal Separation `stems`	Split out the lead vocal, or any single instrument stem.
Full Stem Separation `stems-all`	Separate every instrument and vocal stem at once.
Segment Merge `concat`	Merge the segments produced by extend into one track.

Adjust and export

Endpoint	What it does
Speed Adjustment `adjust-speed`	Change playback speed, optionally preserving pitch.
Multi-format Export `download`	Export as mp3, m4a, or wav.
MIDI Export `gen-midi`	Convert a track to MIDI.

Voices and models

Endpoint	What it does
Voice Capture `persona`	Extract a voice persona from a track for reuse.
Voice Cloning `create-voice`	Clone a reusable voice from a single audio file.
Model Training `create-model`	Train your own style model from 6 to 24 audio files.

Analysis

Endpoint	What it does
Lyric Timings `aligned-lyrics`	Fetch per-line lyric timings plus whole-track waveform data, for karaoke-style highlighting and drawing a track view.
Style Expansion `upsample-tags`	Expand a few short tags into a detailed style description.

Fetch

Endpoint	What it does
Get Task `fetch/{task_id}`	GET. Fetch one task’s status and outputs
Batch Get Tasks `fetch`	Fetch several tasks at once

Pricing

Billing is per call, independent of length or how many results come back:

When an action returns several results and only some succeed, you are charged for the ones that succeeded
max_mode doubles the price and only applies in custom mode
Failed tasks are refunded
Lyric timings (aligned-lyrics) are free

Per-action prices are in the price table on each model’s detail page.

Errors

When a request isn’t accepted, you get a non-2xx status code and a JSON error:

{ "code": "error", "message": "music_id is required" }

Gateway errors such as an invalid token or an unavailable model put the message in an error object:

{ "error": { "message": "Invalid Token", "type": "rix_api_error" } }

Status	Common causes
`400`	Missing or invalid parameters, model unavailable
`401`	Invalid token
`404`	The task doesn’t exist
`429`	Too many requests
`5xx`	Service temporarily unavailable, retry later

If the task was accepted but failed, the fetch result has status set to FAILURE with the reason in fail_reason.

Model APIs

Basics

Call flow

Every endpoint

Create something new

Work on an existing track

Bring your own audio

Split and reassemble

Adjust and export

Voices and models

Analysis

Fetch

Pricing

Errors

Next steps

Suno Quickstart

Suno Workflow Guide

​Basics

​Call flow

​Every endpoint

​Create something new

​Work on an existing track

​Bring your own audio

​Split and reassemble

​Adjust and export

​Voices and models

​Analysis

​Fetch

​Pricing

​Errors

​Next steps

Suno Quickstart

Suno Workflow Guide

Basics

Call flow

Every endpoint

Create something new

Work on an existing track

Bring your own audio

Split and reassemble

Adjust and export

Voices and models

Analysis

Fetch

Pricing

Errors

Next steps