Concepts

Idempotency

Networks fail. With an Idempotency-Key, retrying a POST returns the first result instead of creating a second job or upload.

How it works

Send Idempotency-Key: <unique value> (1 to 255 printable ASCII characters; a UUID is ideal) on POST /v1/files, POST /v1/files/{id}/complete and POST /v1/audio/denoise.
The same key with the same body within 24 hours replays the first response: same status, same body, same job. The work is done once.
The same key with a different body gets 409 idempotency_key_reused.
Keys are scoped to your API key, its mode and the endpoint. A request that failed validation (a 4xx before anything was created) is not stored, so you can fix it and resend with the same key.
After 24 hours the key is forgotten and a reuse counts as a new request.
Replays of POST /v1/files return fresh upload URLs, never stale ones.

Create a job safely, even if the request is retried

KEY=$(uuidgen)   # one key per job you mean to create; reuse it only for retries
# --retry retries timeouts, 429 and 5xx (honouring Retry-After) with the same key;
# any other 4xx (402 insufficient_credit, 409 idempotency_key_reused, ...) fails at once.
curl -s --fail-with-body --retry 4 --retry-connrefused --max-time 30 https://api.zilapi.com/v1/audio/denoise -H "Authorization: Bearer $ZILAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"file": "'"$FILE_ID"'", "model": "zilapi/nr-4.1"}'