Workflow

Add a Vocal Layer

Generate a new vocal performance in a voice style you describe and layer it on top of an existing track, keeping the track's own vocals. Lyrics can be supplied or written for you.

Quickstart
Request fields
How it works
Results and playback
Pricing

Dedicated route only

This workflow uses POST /v1/vocal-layers. It runs a fixed multi-step pipeline; there is no generic tool_id for it.

Quickstart

POST/v1/vocal-layersadd a vocal layer

curl -X POST https://apiv2.soundverse.ai/v1/vocal-layers \
  -H "Authorization: Bearer sksoundverse_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vocal-layer-001" \
  -d '{
  "song_file_id": "018f0000-0000-7000-8000-000000000002",
  "vocal_brief": "angelic soprano harmony",
  "lyrics": "la la la\nsing it back",
  "license": "royalty_free"
}'

The song_file_id must be an active uploaded audio file owned by the authenticated enterprise account.

Getting a song_file_id

Upload the file first via POST /v1/files — either {"source_url": "..."} if you already host it, or a multipart/form-data file part to upload bytes directly. Both return a file_id owned by your account, ready to pass here.

Request fields

Field	Type	Required	Default	Description
song_file_id	uuid	Yes	—	ID of the track to layer the new vocal on, an audio file owned by the authenticated enterprise account (upload it first via POST /v1/files). Its existing vocals are kept. Maximum 60 MiB.
vocal_brief	string	Yes	—	The voice to add: type, singer style or character (e.g. 'angelic soprano harmony layer', 'gravelly male like Tom Waits').
lyrics	string	No	—	The full lyrics to sing, line breaks included. Omit to have original lyrics written for you by the lyric writer (billed as one extra sub-call).
license	license tier	No	"royalty_free"	License tier to price and attach to every step of the pipeline.

How it works

Each request runs 4 steps in order. The first is skipped when you supply lyrics:

Writing lyrics for the new vocal (skipped when you pass lyrics).
Generating the new vocal in the requested voice style.
Layering the new vocal over the original song.
Rendering the finished song into one playable file.

Progress streams over GET /v1/generations/{task_id}/stream as each step starts and finishes.

Notes

Lyrics you pass are used as given. Omit lyrics and lyrics are written for you from the vocal brief (one extra lyric-writer call). The new vocal is layered on top of your track and its existing vocals are kept.

Results and playback

Poll GET /v1/generations/{task_id} until the task is completed. The finished result is added to the authenticated account’s Soundverse Library. Enterprise API outputs are hidden from public/profile surfaces by default.

For API-only download, resolve the output’s file_id with GET /v1/files/{file_id}/url and use the returned short-lived signed URL.

Pricing

This workflow is priced pass-through: you are billed for each step the pipeline runs, at that step’s enterprise rate, in the license tier you requested. The pipeline itself adds no separate fee, and your billing ledger shows one entry per step. The steps that carry the cost are:

Lyric writing (only when lyrics are omitted)
Vocal generation
Mixing
Final render

There is no fixed per-request price; the total depends on the input and on which optional steps run.

← MIDI to SongSong Generation →