MusicAPI
HomeDocs
HomeDocs
  1. sonic
  • Introduction
  • Credits Usage Guide
  • Music API FAQ & Troubleshooting
  • Special Scenarios
  • Error handling
  • Webhook Integration Guide
  • sonic
    • Sonic Instructions
    • create / extend / cover / remaster / add vocals / add instrumental
      POST
    • upload and extend music
      POST
    • upload and cover music
      POST
    • create persona
      POST
    • sample
      POST
    • mashup
      POST
    • get BPM
      POST
    • get VOX
      POST
    • get wav
      POST
    • get midi
      POST
    • get lyrics timeline
      POST
    • upsample tags
      POST
    • stems basic
      POST
    • stems full
      POST
    • replace section
      POST
    • upload music
      POST
    • get music
      GET
  • riffusion(Deprecated)
    • Riffusion instructions
    • create music (with lyrics)
      POST
    • create music (with description)
      POST
    • cover music
      POST
    • extend music
      POST
    • replace music section
      POST
    • swap music sound
      POST
    • swap music vocals
      POST
    • upload
      POST
    • get music
      GET
  • producer
    • Producer instructions
    • Complete Request Examples
    • create music
    • upload
    • download
    • get music
  • studio(Unavailable)
    • Studio Instructions
    • description mode (Use case1)
    • extend mode (Use case2)
    • custom mode (Use case3)
    • instrumental mode (Use case4)
    • get music
  • lyrics generation
    • Make Lyrics
  • nuro
    • Nuro Instruction
    • Error handling
    • create vocal music
    • create instrument music
    • get music
  • get-credits
    GET
  • Schemas
    • 记录不存在
    • 参数不正确
HomeDocs
HomeDocs
  1. sonic

create / extend / cover / remaster / add vocals / add instrumental

POST
https://api.musicapi.ai/api/v1/sonic/create
Unified endpoint for creating, extending, and covering music. The operation is determined by the task_type parameter.
Credits cost: 15 (2 for concat_music)

Task Types#

task_typeDescriptionRequired Parameters
create_musicCreate new music from scratchcustom_mode, mv
extend_musicExtend existing song from a timestampcontinue_clip_id, continue_at, custom_mode, mv
cover_musicCreate cover version of existing songcontinue_clip_id, custom_mode, mv
concat_musicConcatenate songscontinue_clip_id only
persona_musicCreate music with virtual singerpersona_id, custom_mode, mv
remasterRemaster/upgrade existing song qualitycontinue_clip_id, mv
add_instrumentalAdd instrumental to uploaded audiocontinue_clip_id, mv
add_vocalsAdd AI vocals to instrumental trackcontinue_clip_id, mv, prompt (lyrics)

Generation Modes#

Custom Mode (custom_mode: true)#

Provide your own lyrics in the prompt field with structure tags like [Verse], [Chorus], [Bridge], [Outro].

AI Description Mode (custom_mode: false)#

Let AI generate lyrics based on your description in gpt_description_prompt.

Auto Lyrics Mode (auto_lyrics: true)#

Requires custom_mode: true. AI generates lyrics, title, tags based on prompt (song description)

Special Parameters#

Vocal Gender Control#

vocal_gender: 'f' (female) or 'm' (male). Only for sonic-v4-5, sonic-v4-5-plus, sonic-v5.

Audio Weight#

audio_weight (0-1): Controls original audio influence.
For cover_music: Higher = closer to original
For add_instrumental/add_vocals: Controls blend ratio

Style Control#

style_weight (0-1): Style tag influence strength
weirdness_constraint (0-1): Creativity/randomness level

Remaster Parameters#

variation_category: 'subtle', 'normal', 'high' (Only for sonic-v5)

Add Instrumental / Add Vocals Parameters#

overpainting_start_s: Start time (seconds) for adding content
overpainting_end_s: End time (seconds) for adding content

Important Notes#

For add_vocals and add_instrumental#

These task types can only be used with music you uploaded yourself via the upload endpoint. You cannot use them with clips generated by other task types.

Polling Result#

Use get-music endpoint with the returned task_id. Recommended interval: 15-25 seconds.

Related Endpoints#

upload-extend-music: Upload + Extend in one request
upload-cover-music: Upload + Cover in one request
create-persona: Create virtual singer for persona_music

Request

Authorization
JWT Bearer
Add the parameter
Authorization
to Headers
Example:
Authorization: ********************
or
Body Params application/json

Examples
{
    "task_type": "create_music",
    "custom_mode": true,
    "mv": "sonic-v4-5",
    "prompt": "[Verse]\nStars they shine above me\nMoonlight softly glows\nWhispers in the night sky\nDreams that only grow\n\n[Chorus]\nStarry night starry night\nLet your light ignite ignite",
    "title": "Starry Night",
    "tags": "pop, dreamy, emotional"
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request POST 'https://api.musicapi.ai/api/v1/sonic/create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "task_type": "create_music",
    "custom_mode": true,
    "mv": "sonic-v4-5",
    "prompt": "[Verse]\nStars they shine above me\nMoonlight softly glows\nWhispers in the night sky\nDreams that only grow\n\n[Chorus]\nStarry night starry night\nLet your light ignite ignite",
    "title": "Starry Night",
    "tags": "pop, dreamy, emotional"
}'

Responses

🟢200成功
application/json
Success
Body

Example
{
    "code": 200,
    "task_id": "81ed9f60-56ae-48c1-9c46-33a8220dfca7",
    "message": "success"
}
Modified at 2026-01-31 17:03:08
Previous
Sonic Instructions
Next
upload and extend music
Built with