> ## 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 Quickstart

> Generate your first song in five minutes and learn how to collect the result

Suno offers music capabilities covering generation, extension, covers, mashups, stem separation, speed changes, export, and voice training. This page walks you through your first song.

## Generate your first song

The simplest way is to describe what you want in one line.

<CodeGroup dropdown>
  ```bash bash theme={null}
  curl https://api.ephone.ai/suno/v2/music \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mv": "chirp-v6",
      "custom": false,
      "instrumental": false,
      "gpt_description_prompt": "gentle lo-fi piano, rain on a tin roof"
    }'
  ```

  ```python music.py theme={null}
  import requests

  resp = requests.post(
      "https://api.ephone.ai/suno/v2/music",
      headers={"Authorization": f"Bearer {API_KEY}"},
      json={
          "mv": "chirp-v6",
          "custom": False,
          "instrumental": False,
          "gpt_description_prompt": "gentle lo-fi piano, rain on a tin roof",
      },
  )
  task_id = resp.json()["data"]["task_id"]
  ```

  ```javascript music.js theme={null}
  const resp = await fetch("https://api.ephone.ai/suno/v2/music", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      mv: "chirp-v6",
      custom: false,
      instrumental: false,
      gpt_description_prompt: "gentle lo-fi piano, rain on a tin roof",
    }),
  });
  const { data } = await resp.json();
  ```
</CodeGroup>

You get back a task ID:

```json theme={null}
{ "code": "success", "message": "success", "data": { "task_id": "5adac6ee-..." } }
```

## Collect the result

Music generation is asynchronous. Query with the task ID:

```bash theme={null}
curl https://api.ephone.ai/suno/v2/fetch/5adac6ee-... \
  -H "Authorization: Bearer $API_KEY"
```

Once finished, `status` becomes `SUCCESS`:

```json theme={null}
{
  "code": "success",
  "data": {
    "task_id": "5adac6ee-...",
    "action": "music",
    "status": "SUCCESS",
    "progress": "100%",
    "musics": [
      {
        "music_id": "89b20862-...",
        "title": "Rain on Tin Roof",
        "tags": "lo-fi piano",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 187.56
      }
    ]
  }
}
```

<Note>
  Every run returns **two takes** so you can pick the one you like. Lyric writing likewise returns two drafts.
</Note>

To skip polling, pass `notify_hook` when submitting and we will push the result to your endpoint. The payload matches the query response.

To read several tasks at once, use the batch query:

```bash theme={null}
curl -X POST https://api.ephone.ai/suno/v2/fetch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["5adac6ee-...", "7b1f9c22-..."]}'
```

`data` comes back as an array; each item has the same shape as the `data` of a single query.

## Keep the music\_id

The `music_id` in the result is the handle for everything that follows: extending, covering, stem separation, and export all locate the track by it. Store it alongside your task.

## Two ways to call

The example above is the direct form. If you already use the unified task endpoint, this is equivalent in both behaviour and price:

```bash theme={null}
curl https://api.ephone.ai/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno/music",
    "input": {
      "mv": "chirp-v6",
      "custom": false,
      "instrumental": false,
      "gpt_description_prompt": "gentle lo-fi piano, rain on a tin roof"
    }
  }'
```

The model name carries only the action; the model version stays in the parameters, so both forms read the same.

## Write your own lyrics

Turn `custom` on and supply full lyrics in `prompt`. Markers like `[Verse]` and `[Chorus]` shape the structure.

```json theme={null}
{
  "mv": "chirp-v6",
  "custom": true,
  "instrumental": false,
  "title": "Tin Roof Rain",
  "tags": "indie folk, harmonica, mellow",
  "prompt": "[Verse 1]\nRain on the tin roof\nTaps out your name\n\n[Chorus]\nKeep it coming down\nWe're not going anywhere tonight"
}
```

<Warning>
  With `custom` off you must supply `gpt_description_prompt`. With it on you must supply `prompt`, unless you asked for an instrumental.
</Warning>

## Parameters worth knowing

| Parameter       | What it does                                                                   |
| --------------- | ------------------------------------------------------------------------------ |
| `mv`            | Model version. All three cost the same; pick by style                          |
| `duration`      | Length of the result, 10 to 360 seconds                                        |
| `tags`          | The style you want. The more specific, the steadier the result                 |
| `negative_tags` | Styles to steer away from                                                      |
| `vocal_gender`  | Voice gender of the singer                                                     |
| `instrumental`  | Music only, no vocals                                                          |
| `max_mode`      | More compute for whole-song coherence. Custom mode only, **doubles the price** |
| `audio_format`  | Output format, mp3 by default                                                  |

## Choosing a version

| Version         | Best for                            |
| --------------- | ----------------------------------- |
| `chirp-v6`      | Default, balanced                   |
| `chirp-v6-wild` | Bolder styles, good for experiments |
| `chirp-v6-mini` | Faster turnaround                   |

All three cost the same. Defaults to `chirp-v6`.

## What comes next

Once the first song exists you usually want more: make it longer, try another style, pull out the vocal, export as wav. These actions chain together, and some depend on the order you run them in.

<Card title="Suno workflow guide" href="/docs/en/guides/suno-workflows" icon="route">
  Four common chains, plus the full list of capabilities
</Card>