Getting started

Authentication

Every request carries an API key in the Authorization header. Keys belong to your account, come in two modes, and carry scopes.

API keys

Create keys in the dashboard under API keys. The full key is shown once, when you create it; we store only a hash. Send it as a bearer token on every request: Authorization: Bearer zil_live_….

Keep keys on your server, in an environment variable such as ZILAPI_KEY. Never put one in browser or mobile app code, or in a repository.
A key is 256 random bits. Keys do not expire; revoke the ones you no longer use. A revoked key stops working on the next request.
A request without a valid key gets 401 unauthorized. GET /v1/models and GET /v1/status need no key.

Check which key you are using

curl https://api.zilapi.com/v1/me -H "Authorization: Bearer $ZILAPI_KEY"

200 OK · GET /v1/me

{
  "account_id": "acct_2Fq9TzW4nV7k",
  "key_id": "key_8Jd3Lp6Rw1Xs",
  "mode": "live",
  "scopes": ["credits:read", "files:write", "jobs:read", "jobs:write"],
  "balance": { "balance_micros": 48270000, "reserved_micros": 0, "available_micros": 48270000, "currency": "usd", "display": "$48.27" }
}

Live and test modes

Key modes
Property	Live (`zil_live_…`)	Test (`zil_test_…`)
Runs the model	Yes, on our GPUs	No: every job returns the same sample MP3
Costs credit	Yes, per second of audio	Never
Job time	Depends on the audio length	Completes almost at once
File size limit	5 GB and 6 hours	25 MB
Sees	Live files and jobs only	Test files and jobs only

The two modes are fully separate: a test key cannot see, use or delete live files or jobs, and the other way round. A file id from one mode is 404 not_found in the other. Use test keys in CI and local development; they need no credit.

Scopes

Each key carries scopes. New keys get all four. A call without the scope it needs gets 403 insufficient_scope, and detail names the missing scope.

Scopes
Scope	Allows
files:write	`POST /v1/files`, `POST /v1/files/{id}/complete`, `DELETE /v1/files/{id}`, and reading files
jobs:write	`POST /v1/audio/denoise`, `POST /v1/jobs/{id}/cancel`
jobs:read	`GET /v1/jobs`, `GET /v1/jobs/{id}`, `GET /v1/jobs/{id}/output`, and reading files
credits:read	`GET /v1/credits`, and the `balance` in `GET /v1/me`

Account states

If an account is suspended, its keys get 403 account_suspended for new jobs; jobs already running finish. While a card payment dispute is open the account is frozen (403 account_frozen). Email support@zilapi.com in either case.