> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Stems

> Re-run stem separation on an existing project

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

<Columns cols={2}>
  <Card title="Re-run stems when…" icon="arrows-rotate">
    The default model produced muddy vocals, you want to try a different
    algorithm, or you need a specialized output (backing vocals, karaoke-tuned,
    etc.).
  </Card>

  <Card title="Skip this endpoint when…" icon="xmark">
    You're creating a new project — pass `splitModel` to `POST /projects`
    instead of running separation twice.
  </Card>
</Columns>

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

```bash theme={null}
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

<ParamField path="splitModel" type="string" required>
  Stem separation model. See the table below.
</ParamField>

### 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](/en/desktop/split-model) for guidance on picking a model.

## Polling

```bash theme={null}
# 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.

<Tip>
  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.
</Tip>

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

```bash theme={null}
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](/en/api/lyrics-sync) — re-sync lyrics after changing stems
* [Async jobs](/en/api/async-jobs) — polling pattern
* [SDK stems](/en/sdk/stems) — the same endpoint in TypeScript
* [Split model reference](/en/desktop/split-model) — pick the right model