Authentication

Every REST /v1/* endpoint authenticates with an API key. Send it as a bearer token (preferred):

curl -s https://api.kalpalabs.ai/v1/models \
  -H "Authorization: Bearer $KALPA_API_KEY"

or, where headers are awkward to compose, as X-API-Key:

curl -s https://api.kalpalabs.ai/v1/models -H "X-API-Key: $KALPA_API_KEY"

The WebSocket API is the exception: send the key in the first initializeConnection message.

A missing or invalid key returns 401 in the standard envelope:

{ "error": { "type": "authentication_error", "message": "Invalid API key.", "request_id": "…" } }

If key verification is temporarily unavailable on our side, you get 503 with type service_unavailable — retry with the same key; do not treat it as an invalid key.

Keys

• Create keys yourself at kalpalabs.ai/dashboard/keys: new accounts get 1,000 free minutes of generated audio (on your first organization, valid for three months). To rotate a key, create a new one there and revoke the old one; write to hello@kalpalabs.ai to raise its limits.
• Each key carries its own rate limits and its own usage meter.
• Every key belongs to one organization, which holds the usage allowance all its keys draw on. A valid key whose organization is out of allowance gets 402, not 401; a suspended organization gets 403 on every key.
• Treat the key like a password: call the API from your servers, not from browsers or shipped apps. If a key leaks, revoke it in the dashboard and create a new one.

Request IDs

Every HTTP response carries an X-Request-ID header, echoed into error envelopes and our logs. Successful /v1/tts/{voice_id} and /v1/converse bodies also return the same value as request_id. Pass your own X-Request-ID header to correlate with your systems, and include the id when reporting a problem.