Introduction
Understand general concepts, response codes, and authentication strategies for the Speechbase API.
Base URL
The Speechbase API is built on REST principles. We enforce HTTPS on every request to improve data security, integrity, and privacy. The API does not support HTTP.
All requests use the following base URL:
https://api.speechbase.aiAuthentication
Every endpoint except the public /health probe requires an Authorization header carrying a Speechbase API key. Issue keys from the dashboard under Settings → API Keys.
Authorization: Bearer sk_xxxxxxxxA Speechbase key authenticates you to api.speechbase.ai. It is separate from any provider keys you bring along for upstream TTS providers (OpenAI, ElevenLabs, …) — those are how Speechbase is authorised to call out on your behalf, and are managed at Provider Keys (BYOK).
See Authentication for how keys are scoped, rotated, and revoked.
Response codes
Speechbase uses conventional HTTP status codes. 2xx indicates success, 4xx indicates a problem with the request, and 5xx indicates a problem on Speechbase's side or with an upstream provider.
| Status | Description |
|---|---|
200 | Success. The response body contains the result. |
204 | Success with no body. Returned by every DELETE. |
400 | Validation error. The request was malformed; detail names the offending field. |
401 | Missing, malformed, or revoked Speechbase API key. |
403 | The request was blocked. Cross-org access attempt, or fail-closed moderation outage. |
404 | The resource doesn't exist or belongs to another organisation. |
409 | Conflict — typically a duplicate name on a unique-constrained resource. |
422 | Unprocessable. Most commonly a content moderation block. |
503 | Upstream provider is unavailable, or word-level timestamps couldn't be produced. |
See Errors for the full list of domain-specific error codes (content_moderation_blocked, provider_unavailable, timestamps_unavailable, …) and the RFC 7807 Problem Detail body shape used in 4xx and 5xx responses.
Rate limits
Speechbase does not enforce a per-org rate limit at the gateway today. Throughput is usually bounded by provider capacity and the limits each upstream TTS provider applies to your provider key.
Speechbase handles upstream retries and rate-limit responses internally. When a provider returns 429 Too Many Requests or another transient failure, the gateway follows Speechbase's retry and backoff policy before deciding whether the request has failed. You do not need to mirror provider-specific retry behavior in your application.
If those internal attempts are exhausted, Speechbase returns provider_unavailable with status 503. Treat that response as the terminal failure for this API call.