Suno API

RouteAPI provides a unified REST API for Suno AI music generation. Generate music from text, extend songs, clone voices, separate stems, and more.

Base URL: https://api.routeapi.ai
Authentication: Authorization: Bearer sk-xxxx

Workflow Overview

Suno music generation is asynchronous. The typical flow:

Submit a task to /suno/audios → receive a task_id
Wait 2-3 seconds before starting to poll
Poll every 3-5 seconds via /suno/tasks with action: "retrieve"
When status becomes success → fetch the audio_url

Task Status

Status	Meaning	Next Step
`submitted`	Queued for processing	Continue polling
`queued`	Waiting in queue	Continue polling
`in_progress`	Generating	Continue polling
`success`	✅ Complete	Get `data.audio_url`
`failed`	❌ Failed	Check `error` field

Quick Start

Step 1: Submit Task

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "prompt": "A cheerful summer pop song with piano and guitar",
    "async": true
  }'

Response:

{ "success": true, "task_id": "task_xxxxx" }

Step 2: Poll for Result

Poll every 3-5 seconds until status becomes success:

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

Step 3: Get Audio

{
  "id": "task_xxxxx",
  "status": "success",
  "data": {
    "audio_url": "https://cdn.suno.ai/xxx.mp3",
    "video_url": "https://cdn.suno.ai/xxx.mp4",
    "title": "Summer Breeze",
    "duration": 183.5
  }
}

Supported Models

Model ID	Max Duration	Lyric Limit	Style Limit	Title Limit
`chirp-v5-5`	8 minutes	5000 chars	1000 chars	100 chars
`chirp-v5`	8 minutes	5000 chars	1000 chars	100 chars
`chirp-v4-5-plus`	8 minutes	5000 chars	1000 chars	100 chars
`chirp-v4-5`	4 minutes	5000 chars	1000 chars	100 chars
`chirp-v4`	150 seconds	3000 chars	200 chars	80 chars
`chirp-v3-5`	120 seconds	3000 chars	200 chars	80 chars

The prompt field (non-custom mode) has a uniform 500 character limit across all models.

POST /suno/audios

The core endpoint supporting all 18 audio operations.

Core Parameters

Field	Type	Default	Description
`model`	string	`chirp-v4`	Generation model, recommend `chirp-v5-5`
`action`	string	`generate`	Operation type (see below)
`async`	boolean	`false`	Strongly recommended `true` to avoid timeouts

Action Types

Action	Description	Required Fields
`generate`	Generate new music from prompt	`prompt` or `custom=true` + `lyric` + `style`
`extend`	Extend existing audio	`audio_id` + `continue_at`
`concat`	Concatenate audio clips into full track	`audio_id`
`cover`	Re-interpret existing song in new style	`audio_id`
`upload_cover`	Cover uploaded audio	`audio_id` (via `/suno/upload`)
`upload_extend`	Extend uploaded audio	`audio_id` + `continue_at`
`artist_consistency`	Sing with specified Persona	`persona_id` + `lyric` / `prompt`
`artist_consistency_vox`	VOX mode Persona singing (higher quality)	`persona_id` + `lyric` / `prompt`
`stems`	Separate into vocals + instrumental	`audio_id`
`all_stems`	Separate into all tracks (vocals, drums, bass, other)	`audio_id`
`replace_section`	Replace audio segment	`audio_id` + `replace_section_start` + `replace_section_end`
`underpainting`	Add AI instrumental to vocal track	`audio_id` + `underpainting_start` + `underpainting_end`
`overpainting`	Add AI vocals to instrumental track	`audio_id` + `overpainting_start` + `overpainting_end`
`samples`	Add AI samples in time range	`audio_id` + `samples_start` + `samples_end`
`remaster`	Remaster audio to improve quality	`audio_id`
`mashup`	Merge multiple songs	`mashup_audio_ids` (array)
`inspo`	Generate music inspired by 1-4 reference tracks	`audio_urls` (1-4 URLs)

Content Parameters

Field	Type	Description
`prompt`	string	Natural language description of music theme, mood, scene
`lyric`	string	Custom lyrics with section markers like `[Verse]`, `[Chorus]`, `[Bridge]`
`custom`	boolean	Enable custom mode (allows specifying lyrics, title, style)
`instrumental`	boolean	Generate instrumental music (no vocals)
`title`	string	Song title
`style`	string	Style/genre/mood description, comma-separated
`style_negative`	string	Unwanted styles (e.g., “heavy, rock, guitar”)
`duration`	integer	Desired duration in seconds (10-360), hint only in custom mode

Audio Operation Parameters

Field	Type	Description
`audio_id`	string	Existing audio ID (from generation or `/suno/upload`)
`audio_urls`	string[]	Reference audio public URLs (1-4)
`mashup_audio_ids`	string[]	Source audio IDs for mashup
`continue_at`	number	Extend start time (seconds)

Voice & Persona Parameters

Field	Type	Description
`persona_id`	string	Voice persona ID (created via `/suno/persona`)
`vocal_gender`	string	Vocal gender preference: `f` (female) / `m` (male)
`variation_category`	string	Remaster precision: `high` / `normal` / `subtle`

Examples

Simple Generation

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "prompt": "Uplifting electronic dance music with synth lead",
    "async": true
  }'

Custom Lyrics

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "custom": true,
    "title": "Summer Dreams",
    "style": "pop, upbeat, piano",
    "lyric": "[Verse]\nWalking on the beach at sunset\n[Chorus]\nSummer dreams never fade",
    "async": true
  }'

Extend Song

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5",
    "action": "extend",
    "audio_id": "abc123-audio-id",
    "continue_at": 30.5,
    "async": true
  }'

Separate Stems

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "stems",
    "audio_id": "song-to-split",
    "async": true
  }'

POST /suno/tasks

Query task status and results. This is the only way to retrieve results from /suno/audios.

Query Single Task

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

Response:

{
  "id": "task_xxxxx",
  "status": "success",
  "data": {
    "audio_url": "https://cdn.suno.ai/xxx.mp3",
    "video_url": "https://cdn.suno.ai/xxx.mp4",
    "title": "Song Title",
    "text": "Lyrics content",
    "duration": 183.5,
    "model_name": "chirp-v5-5"
  }
}

Batch Query

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve_batch", "ids": ["task_001", "task_002"] }'

POST /suno/lyrics

Generate lyrics that can be used in /suno/audios’s lyric field.

Field	Type	Required	Description
`prompt`	string	✅	Lyrics creation prompt
`model`	string		Default `default`

curl -X POST "https://api.routeapi.ai/suno/lyrics" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Write upbeat summer pop lyrics with chorus" }'

POST /suno/upload

Upload external audio file, returns audio_id for use in extend, cover, voice cloning operations.

curl -X POST "https://api.routeapi.ai/suno/upload" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "audio_url": "https://example.com/my-audio.mp3" }'

GET/POST /suno/persona

Manage voice personas (voice cloning).

GET — List Personas

curl -X GET "https://api.routeapi.ai/suno/persona" \
  -H "Authorization: Bearer sk-xxxx"

POST — Create Persona

curl -X POST "https://api.routeapi.ai/suno/persona" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "uploaded-audio-id",
    "name": "My Voice",
    "vocal_start": 5.0,
    "vocal_end": 15.0
  }'

Other Endpoints

Endpoint	Method	Description
`/suno/voices`	POST	Extract vocal information from audio
`/suno/style`	POST	Generate style description from prompt
`/suno/mashup-lyrics`	POST	Merge two lyrics
`/suno/wav`	POST	Export WAV format (30-day validity)
`/suno/mp4`	POST	Export MP4 video
`/suno/midi`	POST	Export MIDI file
`/suno/timing`	POST	Get lyrics timing for subtitles
`/suno/vox`	POST	Extract vocal segment (remove instrumental)

Error Handling

Status Code	Description
`400`	Invalid request parameters
`401`	Authentication failed
`502`	Upstream service error
`500`	Internal server error

Error response format:

{ "success": false, "error": "error_code", "message": "Detailed error message" }

Best Practices

Polling Code Example (JavaScript)

async function generateAndPoll(prompt) {
  // Submit task
  const res = await fetch('https://api.routeapi.ai/suno/audios', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer sk-xxxx', 'Content-Type': 'application/json' },
    body: JSON.stringify({ model: 'chirp-v5-5', prompt, async: true })
  });
  const { task_id } = await res.json();

  // Wait before first poll
  await new Promise(r => setTimeout(r, 3000));

  const deadline = Date.now() + 3 * 60 * 1000; // 3 min timeout
  while (Date.now() < deadline) {
    const poll = await fetch('https://api.routeapi.ai/suno/tasks', {
      method: 'POST',
      headers: { 'Authorization': 'Bearer sk-xxxx', 'Content-Type': 'application/json' },
      body: JSON.stringify({ action: 'retrieve', id: task_id })
    });
    const result = await poll.json();

    if (result.status === 'success') return result.data;
    if (result.status === 'failed') throw new Error(result.error);

    await new Promise(r => setTimeout(r, 4000)); // Poll every 4s
  }
  throw new Error('Task timeout');
}

FAQ

Q: Which model should I use?
Use chirp-v5-5 (latest and most capable). For stable older version, choose chirp-v4.

Q: How long does generation take?
generate usually 15-40 seconds. Processing operations like stems, all_stems, remaster may take 1-3 minutes.

Q: Can I use audio_url directly?
Yes, the CDN URL is ready for playback or download: curl -o song.mp3 "<audio_url>"

Q: How long is a single generate?
Usually 2-3 minutes. Use extend to continue to 4-5+ minutes by setting continue_at.

Q: Common failure reasons?

Error	Cause	Solution
`prompt_empty`	Missing `prompt` or `lyric`	Provide content fields
`audio_id_required`	Action requires audio_id but not provided	Check required fields for action
`generation_failed`	Content violation or upstream error	Modify prompt and retry
`quota_exceeded`	Insufficient quota	Check account balance

Q: Concurrent request limits?
Yes, depends on account plan. Recommended concurrency ≤ 5, polling interval ≥ 3s.