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

task_type	Description	Credits	Required Parameters
`create_music`	Create new music from scratch	15	`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	15	`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	15	`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	15	`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

Model	Description	Vocal Gender Support
`sonic-v3-5`	Legacy model	No
`sonic-v4`	Improved quality	No
`sonic-v4-5`	Enhanced vocals and instruments	Yes
`sonic-v4-5-all`	fast model	Yes
`sonic-v4-5-plus`	Premium quality	Yes
`sonic-v5`	Latest model with best quality	Yes
`sonic-v5-5`	Latest model with best quality	Yes

Optional Parameters

Vocal Gender Control

Control the singer's gender. Only available for sonic-v4-5, sonic-v4-5-plus, and sonic-v5,sonic-v5-5.

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": "..."
}

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
`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

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

Tags Reference#

Character Limits for tags#

Common Style Tags#

Webhooks#

Polling Results#

Related Endpoints#

Error Handling#