Stems

Stems are the vocal and instrumental tracks extracted from the source audio. Youka separates stems automatically when you create a project. Use this endpoint when you want to re-run separation with a different model — for example, to try a cleaner vocal isolation on a track that sounds muddy.

When to use

Re-run stems when…

The default model produced muddy vocals, you want to try a different algorithm, or you need a specialized output (backing vocals, karaoke-tuned, etc.).

Skip this endpoint when…

You’re creating a new project — pass splitModel to POST /projects instead of running separation twice.

Endpoint

POST /projects/{projectId}/tasks/stem-separation

Returns a taskId you can poll at GET /tasks/{taskId}. The original project state is untouched until the new task finishes.

Request

curl -X POST https://api.youka.io/api/v1/projects/prj_abc/tasks/stem-separation \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: restems-prj_abc-audioshake" \
  -H "Content-Type: application/json" \
  -d '{
    "splitModel": "audioshakeai"
  }'

Fields

string

required

Stem separation model. See the table below.

Available models

Model	Best for
`mdx23c`	Default. Balanced quality and speed.
`audioshakeai`	High-quality AudioShake separation.
`audioshake_vocals_lead`	Vocals and lead vocals only.
`musicai_instrumental_only`	Instrumental-only output.
`musicai_lead_backing_other`	Lead, backing vocals, and other stems.
`musicai_with_backing_vocals`	Vocals including backing tracks.
`musicai_without_backing_vocals`	Lead vocals only.
`uvr_mdxnet_kara_2`	Karaoke-tuned UVR model.
`bs_roformer`	BS-Roformer model.
`mel_band_roformer_instrumental_becruily`	Mel-band Roformer instrumental.
`mel_band_roformer_instrumental_instv7_gabox`	Alternative mel-band instrumental.
`demucs`	Facebook Demucs.

See Split model reference for guidance on picking a model.

Polling

# Poll the task
curl https://api.youka.io/api/v1/tasks/tsk_abc \
  -H "Authorization: Bearer yk_..."

# Once the task is in a terminal state, re-read the project
curl https://api.youka.io/api/v1/projects/prj_abc \
  -H "Authorization: Bearer yk_..."

The updated project.stems array contains the new stem files.

Pair this endpoint with an idempotency key. A retry with the same key and payload returns the original task instead of starting a second separation job.

Download stems

GET /projects/{projectId} returns the current stem files in stems[]. Each stem includes:

Field	Description
`id`	Stem ID, for example `stm_abc`.
`type`	`original`, `instrumental`, `vocals`, or `backing_vocals`.
`model`	Stem separation model that produced the file.
`url`	Direct download URL for the stem file.
`duration`	Stem duration in seconds when known.

Download the url directly. Youka returns the original stored stem format; it does not convert stems during download.

curl https://api.youka.io/api/v1/projects/prj_abc \
  -H "Authorization: Bearer yk_..." \
  | jq -r '.stems[] | select(.type == "instrumental") | .url' \
  | xargs curl -L -o instrumental

What’s next

Lyrics sync — re-sync lyrics after changing stems
Async jobs — polling pattern
SDK stems — the same endpoint in TypeScript
Split model reference — pick the right model

Guides

Resources

API Reference

When to use

Re-run stems when…

Skip this endpoint when…

Endpoint

Request

Fields

Available models

Polling

Download stems

What’s next

​When to use

Re-run stems when…

Skip this endpoint when…

​Endpoint

​Request

​Fields

​Available models

​Polling

​Download stems

​What’s next

When to use

Endpoint

Request

Fields

Available models

Polling

Download stems

What’s next