Tasks

Vocal Separation

Splits a song or mix into a vocal track and an instrumental track. One request in, two MP3s out: vocals and instrumental.

Create a job

POST /v1/audio/separate with the audio and, optionally, the model and a webhook URL. It answers 202 Accepted with the Job and a Location: /v1/jobs/{id} header. Send an Idempotency-Key so a retry never creates a second job. Scopes: jobs:write, plus files:write with input_url or a multipart file (the input becomes a File; 403 insufficient_scope otherwise).

curl -s https://api.zilapi.com/v1/audio/separate \
  -H "Authorization: Bearer $ZILAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"input_url": "https://example.com/demo-song.mp3",
       "model": "zilapi/vms-2.5",
       "webhook_url": "https://your-app.example.com/hooks/zilapi"}' \
  > job.json
JOB_ID=$(jq -r .id job.json)

Request fields
Field	Type	Description
input_url	string	An https URL we fetch: up to 5 GB and 6 hours of audio. The job waits (`waiting_for_file`) until the file is fetched and checked.
file	string	Instead of `input_url`: a `file_…` id from Files. Send exactly one of the two.
model	string	Optional. Default `zilapi/vms-2.5`.
webhook_url	string	Optional. An https URL that receives this job's `job.succeeded`, `job.failed` or `job.canceled` event, signed. See Webhooks.
end_user	string	Optional. Your own id for the user or workspace this job is for: 1 to 128 characters from `A-Z a-z 0-9 . _ : @ -`. Returned on the job; filter with `GET /v1/jobs?end_user=`. Send an opaque or hashed id, never a raw email. See Jobs.

Send a local file

For a file on your machine up to 50 MB (25 MB with a test key), send it in the same request as multipart/form-data: the audio in a field named file, plus model, webhook_url and end_user as fields if you want them. Larger files: upload first, then pass the file id.

curl -s https://api.zilapi.com/v1/audio/separate \
  -H "Authorization: Bearer $ZILAPI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@demo-song.mp3" \
  -F "webhook_url=https://your-app.example.com/hooks/zilapi" \
  > job.json
JOB_ID=$(jq -r .id job.json)

Outputs: vocals and instrumental

A succeeded job lists both files in output.files. Ask for each with GET /v1/jobs/{id}/output?name=…: a signed download URL, valid for up to 1 hour, plus the file's name. Without name you get the first, vocals.

Outputs
Name	Ask with	Filename	Contains
vocals	`?name=vocals`	`<stem>-vocals.mp3`	The voice(s) only, MP3, up to 320 kbps
instrumental	`?name=instrumental`	`<stem>-instrumental.mp3`	Everything except the voice(s), MP3, up to 320 kbps

for NAME in vocals instrumental; do
  curl -s "https://api.zilapi.com/v1/jobs/$JOB_ID/output?name=$NAME" -H "Authorization: Bearer $ZILAPI_KEY" > output.json
  curl -o "$(jq -r .filename output.json)" "$(jq -r .url output.json)"   # <stem>-$NAME.mp3
done

<stem> is your input's filename without its extension. Outputs are deleted 7 days after the job succeeds.

Price and limits

zilapi/vms-2.5 costs $0.033 per audio minute (33,000 micro-dollars per minute), billed per second of the input, with a 1-second minimum per job (min_billable_seconds in GET /v1/models). One price per job: both outputs are included.
Nothing is held while the job waits for its file. Once the file is ready we hold the exact cost; if your available credit is too low, the job fails with insufficient_credit and nothing is charged.
Inputs: common audio formats (WAV, MP3, M4A/AAC, FLAC, OGG/Opus and more, or the audio track of a video), up to 6 hours and 5 GB. Output: MP3, up to 320 kbps.
A rejected input fails the job with invalid_audio, audio_too_long or fetch_failed, and nothing is charged.
For karaoke and backing tracks, remixes, transcription of sung lyrics and practice tracks. You pay once per job, for the input's length: both stems are included.

Statuses, polling and canceling work as for every job: see Jobs. Model details: zilapi/vms-2.5. Compare every model on Pricing.