Get started / Authentication

Authentication#

The API authenticates with an Authorization: Bearer token. Auth is configured on the box, so a public deployment requires a key while an embedded loopback box can run open.

API keys#

Set one or more keys on the server and send it on every /v1 request:

• Single key — ZELI_API_KEY=sk-zeli-...
• Multiple keys — ZELI_API_KEYS=sk-zeli-a,sk-zeli-b (comma-separated)

Sending the key#

Send the key as an Authorization: Bearer header.

curl -X POST "https://voice.your-domain.com/v1/text-to-speech/zeli-voice-1" \
  -H "Authorization: Bearer sk-zeli-..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Authenticated with a Bearer token."}' --output out.mp3

from zeli_tts import ZeliSpeech
 
# The SDK sends the key automatically.
client = ZeliSpeech(api_key="sk-zeli-...", base_url="https://voice.your-domain.com")

WebSocket authentication#

The realtime stream-input WebSocket reads the key from either of two places:

1. The BOS message field authorization (a Bearer sk-zeli-... token).
2. A ?authorization=Bearer%20sk-zeli-... query parameter (for browser clients that can't set headers).

{ "text": " ", "authorization": "Bearer sk-zeli-...", "voice_settings": { "stability": 0.5 } }

See Realtime WebSocket for the full protocol.

Errors#

Auth failures use the ZeliSpeech error envelope:

{ "detail": { "status": "missing_api_key", "message": "..." } }

See Errors for the complete list.

Provisioning a public box#

Per-key concurrency limits, queueing, and 429 rate limiting are on the roadmap (the engine is batch-1, so concurrency control matters for public boxes).