Suno Quickstart

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.

bash

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"
  }'

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"]

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();

You get back a task ID:

{ "code": "success", "message": "success", "data": { "task_id": "5adac6ee-..." } }

Collect the result

Music generation is asynchronous. Query with the task ID:

curl https://api.ephone.ai/suno/v2/fetch/5adac6ee-... \
  -H "Authorization: Bearer $API_KEY"

Once finished, status becomes SUCCESS:

{
  "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
      }
    ]
  }
}

Every run returns two takes so you can pick the one you like. Lyric writing likewise returns two drafts.

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:

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:

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.

{
  "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"
}

With custom off you must supply gpt_description_prompt. With it on you must supply prompt, unless you asked for an instrumental.

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.

Suno workflow guide

Four common chains, plus the full list of capabilities

Getting Started

Models & Services

Usage Guide

Generate your first song

Collect the result

Keep the music_id

Two ways to call

Write your own lyrics

Parameters worth knowing

Choosing a version

What comes next

Suno workflow guide

​Generate your first song

​Collect the result

​Keep the music_id

​Two ways to call

​Write your own lyrics

​Parameters worth knowing

​Choosing a version

​What comes next

Suno workflow guide

Generate your first song

Collect the result

Keep the music_id

Two ways to call

Write your own lyrics

Parameters worth knowing

Choosing a version

What comes next