Getting started

Quickstart

Denoise one audio file with zilapi/nr-4.1 in five steps. With a test key this costs nothing; with a live key, a 3-minute file costs about $0.10.

Before you start: you need a ZilAPI account and an API key in ZILAPI_KEY. Create a key (a test key is fine). The curl examples use jq and bash; Python uses requests; JavaScript runs on Node 20 or later as an ES module.

Start an upload

Tell us the file name, size in bytes and audio type. You get a file id and a signed upload URL, valid for a limited time. Files up to 5 GB and 6 h are accepted; this example covers a single PUT, which is what you get for files up to 100 MB. Test keys accept files up to 25 MB.

curl -s https://api.zilapi.com/v1/files \
  -H "Authorization: Bearer $ZILAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "talk.wav", "size_bytes": '"$(wc -c < talk.wav)"', "content_type": "audio/wav"}' \
  > upload.json

FILE_ID=$(jq -r .id upload.json)   # file_3Lm8QpZ2rT6w

Upload the bytes

PUT the file to upload.url and send every header in upload.headers with it. The bytes go straight to storage, not through the API.

mapfile -t HEADERS < <(jq -r '.upload.headers | to_entries[] | "-H", "\(.key): \(.value)"' upload.json)

curl -X PUT "$(jq -r .upload.url upload.json)" "${HEADERS[@]}" --data-binary @talk.wav

Finish the upload and wait until it is ready

Finishing starts validation: we check the size and measure the audio. The file is validating for a few seconds, then ready (with duration_seconds) or rejected (not audio, or longer than 6 h).

curl -s -X POST https://api.zilapi.com/v1/files/$FILE_ID/complete \
  -H "Authorization: Bearer $ZILAPI_KEY"

while :; do
  FILE_STATUS=$(curl -s https://api.zilapi.com/v1/files/$FILE_ID -H "Authorization: Bearer $ZILAPI_KEY" | jq -r .status)
  [ "$FILE_STATUS" != "validating" ] && break
  sleep 2
done
echo "$FILE_STATUS"   # ready

Create a denoise job

Name the file and the model. The job is queued and runs on our GPUs. With a live key we hold the exact cost from your credit; if your available credit is too low you get 402 insufficient_credit and nothing starts.

curl -s https://api.zilapi.com/v1/audio/denoise \
  -H "Authorization: Bearer $ZILAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file": "'"$FILE_ID"'", "model": "zilapi/nr-4.1"}' \
  > job.json

JOB_ID=$(jq -r .id job.json)   # job_7Hq2xV9mKp4R

Wait for the job, then download the MP3

Poll every few seconds while the job is queued or processing. When it has succeeded, ask for a fresh download URL (valid for 1 hour). Results are kept for 7 days after the job succeeds.

while :; do
  STATUS=$(curl -s https://api.zilapi.com/v1/jobs/$JOB_ID -H "Authorization: Bearer $ZILAPI_KEY" | jq -r .status)
  case "$STATUS" in queued|processing) sleep 5 ;; *) break ;; esac
done
echo "$STATUS"   # succeeded

curl -s https://api.zilapi.com/v1/jobs/$JOB_ID/output -H "Authorization: Bearer $ZILAPI_KEY" > output.json
curl -o "$(jq -r .filename output.json)" "$(jq -r .url output.json)"

Errors you may see

Errors are application/problem+json with a code, a detail and a request_id to quote if you contact us. Only a succeeded job is ever charged.

Status	Code	Meaning
402	insufficient_credit	Available credit is below the job's cost. Nothing started, nothing charged.
409	file_not_ready	The file is still validating. Poll GET /v1/files/{id} until it is ready.
413	file_too_large	Over 5 GB. Split or compress the file.
415	unsupported_media_type	content_type is not a common audio type.
422	audio_too_long / invalid_audio	Longer than 6 h, or not audio we can decode. The file is rejected.
409	job_not_cancelable	Jobs can be canceled only while queued.
410	output_expired	Results are deleted 7 days after the job succeeds.
429	rate_limited	Over 120 creates or 1,200 reads per minute for this key. Wait Retry-After seconds.