Sonic API Instructions

The Sonic API enables AI-powered music generation with multiple modes and advanced controls. This guide covers all available features and parameters.

Quick Start

Task Types

Every model costs the same. Generation-type task types cost 20 credits; extend-type task types cost 15. See the Credits Usage Guide for the full per-operation table.

task_type	Description	Credits	Required Parameters
`create_music`	Create new music from scratch	20	`custom_mode`, `mv`
`extend_music`	Extend an existing song from a timestamp	15	`continue_clip_id`, `continue_at`, `custom_mode`, `mv`
`cover_music`	Create a cover version with style transformation	20	`continue_clip_id`, `custom_mode`, `mv`
`concat_music`	Concatenate/merge songs together	2	`continue_clip_id` only
`persona_music`	Generate music with a virtual singer's voice	20	`persona_id`, `custom_mode`, `mv`
`extend_upload_music`	Extend your own uploaded music	15	`continue_clip_id`, `continue_at`, `custom_mode`, `mv`
`cover_upload_music`	Cover your own uploaded music	20	`continue_clip_id`, `custom_mode`, `mv`

Important: When extending or covering your own uploaded music (via the upload endpoint), you must use extend_upload_music or cover_upload_music task types instead of extend_music or cover_music.

Generation Modes

Custom Mode (`custom_mode: true`)

Provide your own lyrics with full control over song structure.

{
  "custom_mode": true,
  "mv": "sonic-v4-5",
  "title": "Starry Night",
  "tags": "pop, dreamy",
  "prompt": "[Verse]\nStars they shine above me\nMoonlight softly glows\n\n[Chorus]\nStarry night, starry night\nLet your light ignite"
}

Supported Structure Tags:

[Verse] - Main verses

[Chorus] - Repeated chorus sections

[Pre-Chorus] - Build-up before chorus

[Bridge] - Contrasting middle section

[Outro] - Ending section

[Intro] - Opening section

[Hook] - Catchy repeated phrase

[Break] - Instrumental break

Character Limits for prompt:

Model Version	Max Characters
sonic-v3-5, sonic-v4	3,000
sonic-v4-5, sonic-v4-5-plus, sonic-v5, sonic-v5-5	5,000

AI Description Mode (`custom_mode: false`)

Let AI generate lyrics based on your description.

{
  "custom_mode": false,
  "mv": "sonic-v4-5",
  "gpt_description_prompt": "An upbeat summer pop song about road trips and freedom, with catchy hooks and positive energy"
}

Character Limit: gpt_description_prompt max 400 characters.

Auto Lyrics Mode (`auto_lyrics: true`)

AI automatically generates lyrics,title,tags based on prompt. Requires custom_mode: true.

{
  "custom_mode": true,
  "auto_lyrics": true,
  "mv": "sonic-v4-5",
  "prompt":"pop song",
  "title": "Midnight Dreams",
  "tags": "r&b, smooth, romantic"
}

Model Versions

Suno v6 — updated 2026-09-09. Suno released v6 and retired v3.5 through
v5.5 on its own platform. All three v6 models are selectable here:
sonic-v6, sonic-v6-wild and sonic-v6-mini.
Nothing you send has to change. Every older mv value is still accepted;
Suno maps the retired ids onto v6, so a request naming one of them runs v6.
⚠️ What did change is the credit cost. A generation is now 20 credits on
every model. sonic-v3-5 and sonic-v4 used to cost 15, because Suno
charged less to run them — they no longer select a cheaper model, so they no
longer cost less. See the Credits Usage Guide and the
API Changelog.

Model	Description	Vocal Gender Support
`sonic-v6`	Latest model	Yes
`sonic-v6-wild`	Latest model, experimental output	Yes
`sonic-v6-mini`	Latest model, smaller and faster	Yes
`sonic-v5-5`	Retired by Suno; served by v6	Yes
`sonic-v5`	Retired by Suno; served by v6	Yes
`sonic-v4-5-plus`	Retired by Suno; served by v6	Yes
`sonic-v4-5`	Retired by Suno; served by v6	Yes
`sonic-v4-5-all`	Retired by Suno; served by v6	Yes
`sonic-v4`	Retired by Suno; served by v6	No
`sonic-v3-5`	Retired by Suno; served by v6	No

Optional Parameters

Vocal Gender Control

Control the singer's gender. Available on every model except sonic-v3-5 and sonic-v4.

Value	Description
`f`	Female vocal
`m`	Male vocal

{
  "custom_mode": true,
  "mv": "sonic-v4-5",
  "vocal_gender": "f",
  "prompt": "...",
  "tags": "pop, female vocal"
}

Instrumental Mode

Generate music without vocals.

{
  "custom_mode": false,
  "mv": "sonic-v4-5",
  "make_instrumental": true,
  "gpt_description_prompt": "A peaceful piano melody with soft strings"
}

Style Control

Fine-tune the generation with these parameters:

Parameter	Range	Description
`style_weight`	0 - 1	How strongly style tags influence output. Higher = stronger adherence to tags.
`weirdness_constraint`	0 - 1	Creativity/randomness level. Higher = more experimental/unusual output.

{
  "custom_mode": true,
  "mv": "sonic-v4-5",
  "style_weight": 0.8,
  "weirdness_constraint": 0.3,
  "tags": "electronic, synthwave",
  "negative_tags": "acoustic, folk",
  "prompt": "..."
}

Negative Tags

Exclude unwanted styles or elements from the generated music.

{
  "tags": "pop, modern",
  "negative_tags": "country, folk, acoustic, slow"
}

Audio Weight (Cover Only)

For cover_music task type only. Controls how much the original audio influences the cover.

Value	Effect
0	Minimal original influence, maximum creative freedom
0.5	Balanced mix
1	Maximum original influence, closer to source

{
  "task_type": "cover_music",
  "continue_clip_id": "original-clip-id",
  "audio_weight": 0.6,
  "tags": "jazz, smooth",
  "custom_mode": true,
  "mv": "sonic-v4-5",
  "prompt": "..."
}

Song Length (`duration`)

Sets a target length for the generated track, in seconds.

Field	Range	Notes
`duration`	10 - 360	Integer seconds. Works in both custom mode and AI description mode.

The result lands close to the requested length rather than exactly on it — a
request for 45 typically returns clips of roughly 43-45 seconds. Ask for a target,
not a hard cut.

Supported on create_music, persona_music, extend_music, cover_music,
extend_upload_music and cover_upload_music, plus the /upload-cover and
/upload-extend endpoints. Sending it with any other task type returns a
validation error rather than being silently ignored.

{
  "task_type": "create_music",
  "custom_mode": false,
  "mv": "sonic-v5",
  "gpt_description_prompt": "upbeat lo-fi study beat",
  "duration": 90
}

Tags Reference

Character Limits for `tags`

Model Version	Max Characters
sonic-v3-5, sonic-v4	200
sonic-v4-5, sonic-v4-5-plus, sonic-v5	1,000

Common Style Tags

Genres: pop, rock, jazz, electronic, hip-hop, r&b, country, folk, classical, metal, punk, reggae, blues, soul, funk, disco, house, techno, ambient, lo-fi

Moods: happy, sad, energetic, calm, romantic, dark, uplifting, melancholic, aggressive, peaceful, dreamy, nostalgic

Instruments: piano, guitar, acoustic, electric guitar, bass, drums, violin, saxophone, synthesizer, orchestra

Vocals: male vocal, female vocal, choir, harmonies, falsetto, rap, spoken word

Tempo: slow, mid-tempo, fast, upbeat, downtempo

Era/Style: 80s, 90s, retro, modern, vintage, futuristic, cinematic, epic

Webhooks

Receive notifications when tasks complete instead of polling.

{
  "custom_mode": true,
  "mv": "sonic-v4-5",
  "prompt": "...",
  "webhook_url": "https://your-server.com/webhook",
  "webhook_secret": "your-secret-key"
}

The webhook payload will be signed using webhook_secret for verification.

Polling Results

After creating a task, poll the result using the get-music endpoint:

Recommended polling interval: 15-25 seconds

Task States:

State	Description
`pending`	Task is queued
`running`	Task is processing
`succeeded`	Task completed successfully
`failed`	Task failed

Endpoint	Description
upload-extend-music	One-stop API: upload + extend in single request
upload-cover-music	One-stop API: upload + cover in single request
create-persona	Create virtual singer from existing song
get-music	Poll task results
upload-music	Upload audio file to get clip_id
get-bpm	Get BPM information of a song
get-vox	Extract vocals from a song

Error Handling

Common validation errors:

Error	Cause	Solution
`mv field is invalid`	Invalid model version	Use one of: sonic-v3-5, sonic-v4, sonic-v4-5, sonic-v4-5-plus, sonic-v5, sonic-v5-5
`prompt length exceeded`	Lyrics too long	Reduce to 3000 (v4-) or 5000 (v4.5+) characters
`gpt_description_prompt length exceeded`	Description too long	Reduce to 400 characters
`tags length exceeded`	Tags too long	Reduce to 200 (v4-) or 1000 (v4.5+) characters
`continue_clip_id is required`	Missing source clip	Provide clip_id for extend/cover/concat tasks
`persona_id is required`	Missing persona	Provide persona_id for persona_music task
`audio_weight should be 0-1`	Invalid audio weight	Use value between 0 and 1
`The duration should be an integer number of seconds.`	Non-integer duration	Send a whole number, e.g. `90`, not `"90"` or `90.5`
`The duration should be between 10 and 360 seconds.`	Duration out of range	Use a value from 10 to 360

Sonic Instructions

Sonic API Instructions#

Quick Start#

Task Types#

Generation Modes#

Custom Mode (custom_mode: true)#

AI Description Mode (custom_mode: false)#

Auto Lyrics Mode (auto_lyrics: true)#

Model Versions#

Optional Parameters#

Vocal Gender Control#

Instrumental Mode#

Style Control#

Negative Tags#

Audio Weight (Cover Only)#

Song Length (duration)#

Tags Reference#

Character Limits for tags#

Common Style Tags#

Webhooks#

Polling Results#

Related Endpoints#

Error Handling#