> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rixapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno API Overview

> Call flow, authentication, every endpoint, pricing and errors

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

**1. Submit a task**

Call the endpoint for the action, for example [Music Generation](https://docs.rixapi.com/docs/en/api-reference/suno/music.md). `data.task_id` in the response is the task ID.

**2. Get the result**

Poll [Get Task](https://docs.rixapi.com/docs/en/api-reference/suno/fetch.md) every 3 to 5 seconds until `status` becomes `SUCCESS` or `FAILURE`; use [Batch Get Tasks](https://docs.rixapi.com/docs/en/api-reference/suno/fetch-batch.md) for several at once. Or pass `notify_hook` on submission and we POST the same content as the fetch result when the task ends.

**3. 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.

> [!TIP]
>
> 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](https://docs.rixapi.com/docs/en/api-reference/suno/music.md) `music` | Generate a full song from a one-line idea or your own lyrics. Returns two takes. |
| [Lyric Writing](https://docs.rixapi.com/docs/en/api-reference/suno/lyrics.md) `lyrics` | Write lyrics from a theme. Returns two drafts. |
| [Sound Effects](https://docs.rixapi.com/docs/en/api-reference/suno/sounds.md) `sounds` | Generate one-shot or looping sound effects, with optional BPM and key. |
| [Reference Generation](https://docs.rixapi.com/docs/en/api-reference/suno/inspo.md) `inspo` | Create from one to four reference tracks as style guides. |
| [Sample Rework](https://docs.rixapi.com/docs/en/api-reference/suno/sample.md) `sample` | Chop a sample and build a new track around it. |
| [Mashup](https://docs.rixapi.com/docs/en/api-reference/suno/mashup.md) `mashup` | Blend two tracks into a new one. |

### Work on an existing track

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

### Bring your own audio

| Endpoint | What it does |
| - | - |
| [Audio Upload](https://docs.rixapi.com/docs/en/api-reference/suno/upload.md) `upload` | Upload audio so other actions can reference it. |
| [Upload & Cover](https://docs.rixapi.com/docs/en/api-reference/suno/upload-cover.md) `upload-cover` | Upload your own audio and re-perform it in a new style. |
| [Upload & Extend](https://docs.rixapi.com/docs/en/api-reference/suno/upload-extend.md) `upload-extend` | Upload your own audio and continue it from a given point. |

### Split and reassemble

| Endpoint | What it does |
| - | - |
| [Vocal Separation](https://docs.rixapi.com/docs/en/api-reference/suno/stems.md) `stems` | Split out the lead vocal, or any single instrument stem. |
| [Full Stem Separation](https://docs.rixapi.com/docs/en/api-reference/suno/stems-all.md) `stems-all` | Separate every instrument and vocal stem at once. |
| [Segment Merge](https://docs.rixapi.com/docs/en/api-reference/suno/concat.md) `concat` | Merge the segments produced by extend into one track. |

### Adjust and export

| Endpoint | What it does |
| - | - |
| [Speed Adjustment](https://docs.rixapi.com/docs/en/api-reference/suno/adjust-speed.md) `adjust-speed` | Change playback speed, optionally preserving pitch. |
| [Multi-format Export](https://docs.rixapi.com/docs/en/api-reference/suno/download.md) `download` | Export as mp3, m4a, or wav. |
| [MIDI Export](https://docs.rixapi.com/docs/en/api-reference/suno/gen-midi.md) `gen-midi` | Convert a track to MIDI. |

### Voices and models

| Endpoint | What it does |
| - | - |
| [Voice Capture](https://docs.rixapi.com/docs/en/api-reference/suno/persona.md) `persona` | Extract a voice persona from a track for reuse. |
| [Voice Cloning](https://docs.rixapi.com/docs/en/api-reference/suno/create-voice.md) `create-voice` | Clone a reusable voice from a single audio file. |
| [Model Training](https://docs.rixapi.com/docs/en/api-reference/suno/create-model.md) `create-model` | Train your own style model from 6 to 24 audio files. |

### Analysis

| Endpoint | What it does |
| - | - |
| [Lyric Timings](https://docs.rixapi.com/docs/en/api-reference/suno/aligned-lyrics.md) `aligned-lyrics` | Fetch per-line lyric timings plus whole-track waveform data, for karaoke-style highlighting and drawing a track view. |
| [Style Expansion](https://docs.rixapi.com/docs/en/api-reference/suno/upsample-tags.md) `upsample-tags` | Expand a few short tags into a detailed style description. |

### Fetch

| Endpoint | What it does |
| - | - |
| [Get Task](https://docs.rixapi.com/docs/en/api-reference/suno/fetch.md) `fetch/{task_id}` | GET. Fetch one task's status and outputs |
| [Batch Get Tasks](https://docs.rixapi.com/docs/en/api-reference/suno/fetch-batch.md) `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:

```json theme={null}
{ "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:

```json theme={null}
{ "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`.

## Next steps

> [card] [Suno Quickstart](https://docs.rixapi.com/docs/en/guides/suno-quickstart.md)
>
> Generate your first song, pick a model version, write your own lyrics

> [card] [Suno Workflow Guide](https://docs.rixapi.com/docs/en/guides/suno-workflows.md)
>
> Full songs, reworks, stems, reusable voices and other common flows


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.