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.wav

That'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

POST/api/v1/tts

Generates audio from text. Returns audio/wav plus billing headers.

Request body

ParameterTypeDescription
textrequiredstringThe text to synthesize. Max 1024 characters.
voicestringVoice ID. Default: tongtong. See /api/v1/voices.
speednumberSpeech speed, 0.5–2.0. Default: 1.0.

Response headers

ParameterTypeDescription
X-Sonara-Credits-SpentintegerCredits debited for this request.
X-Sonara-BalanceintegerRemaining credit balance.
X-Sonara-Request-IduuidUnique request ID (use for support + idempotency).
X-RateLimit-RemainingintegerRequests 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();
javascript

Voices

GET/api/v1/voices

Lists 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 · Friendly
xiaochen·ColeSteady · Professional
jam·RowanRefined · British
chuichui·MiraBright · Expressive
kazi·SageClear · Neutral
douji·NicoNatural · Conversational
luodo·VegaResonant · Cinematic

Errors & Rate Limits

HTTP status codes

ParameterTypeDescription
200SuccessAudio generated successfully.
400Bad RequestMissing or invalid text.
401UnauthorizedMissing or invalid API key.
402Payment RequiredInsufficient credits.
413Payload Too LargeText exceeds 1024 chars.
429Too Many RequestsRate limit exceeded. See Retry-After header.
503Service UnavailableUpstream 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:

ParameterTypeDescription
checkout.session.completedeventA credit pack was purchased.
invoice.paideventA subscription renewed; monthly credits granted.
customer.subscription.deletedeventA 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