Getting Started

The Sonna REST API lets you generate speech (Text-to-Speech) programmatically — the same engines that power the Web and Android apps. This page covers the conventions shared by every endpoint.

Base URL

All API requests are made to:

https://api.sonnalabs.app

Authentication

Authenticate every request with a developer API key (sona_sk_...) in either header:

Authorization: Bearer sona_sk_your_api_key_here

X-API-Key: sona_sk_your_api_key_here

API keys can only be created by paying users (active Pro/Max subscription or a positive PAYG balance). Requests authenticated with an API key also receive a 10% credit discount on Speech. See Authentication.

Path versioning

Sonna's routes are not uniformly versioned — some sit under /api/v1/ and others directly under /api/. Use the exact path documented for each endpoint. The prefixes you'll use:

Request & response conventions

• Request and response bodies are JSON (Content-Type: application/json).
• Successful responses include "success": true and return the result directly.
• Speech synthesis is synchronous — the response carries the finished audio URL; there is no job_id and no polling.
• Credits are deducted upfront and refunded automatically if synthesis fails. See Errors & Refunds.

Error shape

Failed requests return a non-2xx status with an error message, and where applicable a machine-readable code:

{
  "error": "Too many requests. Please wait."
}

Next steps