Suno add-vocal vs add-instrumental: API Workflow

Short answer: use POST /api/music/add-vocal when the backing track already exists and needs vocals or a vocal rewrite. Use POST /api/music/add-instrumental when a song needs new instruments or a rebuilt accompaniment. Both require a real completed source_clip_id.

Choose the direction

Add vocal example

curl -X POST "https://www.suno-api.io/api/music/add-vocal" \
  -H "Authorization: Bearer $SUNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "source_clip_id": "source_song_id",
    "lyrics": "[Verse]\nCity lights in the rain\n[Chorus]\nWe keep moving on",
    "style_tags": "warm male vocal, intimate pop",
    "instrumental": false
  }'

Add instrumental example

curl -X POST "https://www.suno-api.io/api/music/add-instrumental" \
  -H "Authorization: Bearer $SUNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "source_clip_id": "source_song_id",
    "style_tags": "cinematic strings and acoustic guitar",
    "audio_weight": 1,
    "duration": 60
  }'

audio_weight and duration

audio_weight ranges from 0-1 and controls reliance on the reference audio. duration ranges from 1-480 seconds, although practical output is usually at least about 30 seconds.

When to use another endpoint

• New sung interpretation: cover.
• Split vocals and backing: separate.
• Add one individual instrument track: add-stem.
• Fix one short range: replace-section.

FAQ

What is the difference between add-vocal and a cover?

Add-vocal is focused on generating vocals on an existing source. Use cover for a new sung version workflow.

Does add-instrumental return individual instrument tracks?

No. It creates a new accompaniment result, not separated tracks.

Can source_clip_id be a pending placeholder?

No. It must be completed and accessible.

Read the add-vocal API, add-instrumental API, and 12-stem guide.

← Back to all articles