API Documentation
The Sonara REST API. Base URL: https://your-domain/api/v1
Quickstart
Make your first request in under a minute. Sign up, grab an API key from the dashboard, and call the TTS endpoint:
curl -X POST https://your-domain/api/v1/tts \
-H "Authorization: Bearer sk_sonara_..." \
-H "Content-Type: application/json" \
-d '{
"text": "Hello, world!",
"voice": "tongtong",
"speed": 1.0
}' \
--output hello.wavThat's it. You'll get back a WAV audio file plus billing headers showing credits spent and your remaining balance.
Authentication
All API requests must be authenticated with a Bearer API key. Get yours from the API Keys dashboard.
curl https://your-domain/api/v1/tts \
-H "Authorization: Bearer sk_sonara_..."
Key format
Keys start with sk_sonara_ and carry 256 bits of entropy. They are stored hashed (SHA-256 + salt) — if you lose a key, revoke it and create a new one. Treat keys like passwords; never expose them in client-side code.
Text to Speech
/api/v1/ttsGenerates audio from text. Returns audio/wav plus billing headers.
Request body
| Parameter | Type | Description |
|---|---|---|
textrequired | string | The text to synthesize. Max 1024 characters. |
voice | string | Voice ID. Default: tongtong. See /api/v1/voices. |
speed | number | Speech speed, 0.5–2.0. Default: 1.0. |
Response headers
| Parameter | Type | Description |
|---|---|---|
X-Sonara-Credits-Spent | integer | Credits debited for this request. |
X-Sonara-Balance | integer | Remaining credit balance. |
X-Sonara-Request-Id | uuid | Unique request ID (use for support + idempotency). |
X-RateLimit-Remaining | integer | Requests remaining in the current window. |
Example (JavaScript)
const res = await fetch("/api/v1/tts", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SONARA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
text: "The harbor shimmered under a pale dawn.",
voice: "tongtong",
speed: 1.0,
}),
});
const audioBlob = await res.blob();
console.log("Credits spent:", res.headers.get("X-Sonara-Credits-Spent"));
console.log("Balance:", res.headers.get("X-Sonara-Balance"));
// Play the audio
const url = URL.createObjectURL(audioBlob);
new Audio(url).play();javascriptVoices
/api/v1/voicesLists all available voices. No auth required.
curl https://your-domain/api/v1/voices
# Response:
{
"ok": true,
"voices": [
{ "id": "tongtong", "name": "Aria", "category": "Narration", ... },
...
]
}Available voices
tongtong·AriaWarm · Friendlyxiaochen·ColeSteady · Professionaljam·RowanRefined · Britishchuichui·MiraBright · Expressivekazi·SageClear · Neutraldouji·NicoNatural · Conversationalluodo·VegaResonant · CinematicErrors & Rate Limits
HTTP status codes
| Parameter | Type | Description |
|---|---|---|
200 | Success | Audio generated successfully. |
400 | Bad Request | Missing or invalid text. |
401 | Unauthorized | Missing or invalid API key. |
402 | Payment Required | Insufficient credits. |
413 | Payload Too Large | Text exceeds 1024 chars. |
429 | Too Many Requests | Rate limit exceeded. See Retry-After header. |
503 | Service Unavailable | Upstream model temporarily unavailable. |
Rate limits
Limits are per-user (across all keys) and follow a token-bucket algorithm. The Free plan allows 20 requests/min; paid plans scale up to 2,400 rpm.
# When rate limited, you'll get:
HTTP/1.1 429 Too Many Requests
Retry-After: 14
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
{
"ok": false,
"error": "rate_limit_exceeded",
"retry_after_seconds": 14
}Idempotency
Send an X-Request-Id header to make a request idempotent. If you retry with the same ID, you won't be charged twice.
Webhooks
Sonara sends webhook events for billing activity. Configure your endpoint in the dashboard, and we'll POST to it on:
| Parameter | Type | Description |
|---|---|---|
checkout.session.completed | event | A credit pack was purchased. |
invoice.paid | event | A subscription renewed; monthly credits granted. |
customer.subscription.deleted | event | A subscription was canceled; downgraded to Free. |
// Your webhook handler (Next.js example)
export async function POST(req: Request) {
const event = await req.json();
// Verify signature in production!
switch (event.type) {
case "checkout.session.completed":
const credits = event.data.object.metadata.credits;
console.log(`Grant ${credits} credits`);
break;
case "invoice.paid":
console.log("Subscription renewed");
break;
}
return new Response("ok");
}javascript