Build Your First App with the Sonna API in 10 Minutes

The Sonna API gives you programmatic access to every generation feature on the platform — text-to-speech, image generation, and music generation — through a consistent, straightforward interface. This quickstart walks you from zero to a working integration in under 10 minutes.

---

Prerequisites

Before you write a single line of code, you need:

1. A Sonna account with a Pro plan, Max plan, or PAYG credits — Free accounts cannot create API keys
2. API credits to consume (your subscription or PAYG balance)

That's it. No separate API tier to subscribe to, no additional billing setup.

---

Step 1: Create Your API Key

Navigate to Sonna Console → API Keys.

Click Create Key, enter a descriptive name (e.g., my-app-dev), and confirm. Your new key is displayed once — copy it immediately and store it securely. Sonna does not store retrievable copies of your keys.

Your key will look like this:

sona_sk_1a2b3c4d5e6f7g8h9i0j...

Keep a maximum of 10 active keys per account. Revoke unused keys from the same page when they're no longer needed.

---

Step 2: Authenticate Your Requests

The Sonna API accepts two equivalent authentication formats. Use whichever fits your stack:

Option A — X-API-Key header (recommended for server-side):

X-API-Key: sona_sk_YOUR_KEY_HERE

Option B — Bearer token:

Authorization: Bearer sona_sk_YOUR_KEY_HERE

Both headers work on every endpoint. Never send your API key in a URL query parameter or expose it in client-side JavaScript.

---

Step 3: Your First TTS Request

The TTS endpoint is POST /api/v1/tts/synthesize. Here's a minimal request that generates speech using ElevenLabs Flash v2.5:

curl:

curl -X POST https://sonnalabs.app/api/v1/tts/synthesize \
  -H "X-API-Key: sona_sk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to Sonna. Your generation is ready.",
    "voice": "YOUR_VOICE_ID",
    "ttsModel": "eleven-flash-v2-5"
  }'

JavaScript (fetch):

const response = await fetch("https://sonnalabs.app/api/v1/tts/synthesize", {
  method: "POST",
  headers: {
    "X-API-Key": "sona_sk_YOUR_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Welcome to Sonna. Your generation is ready.",
    voice: "YOUR_VOICE_ID",
    ttsModel: "eleven-flash-v2-5",
  }),
});

const audioBlob = await response.blob();

Replace YOUR_VOICE_ID with a voice ID from your Sonna account. You can browse available voices from the Creative section of the app.

Popular ttsModel values:

• "eleven-flash-v2-5" — fast, affordable (1.05 cr/char)
• "eleven-multilingual-v2" — high quality (2.10 cr/char)
• "eleven-v3" — most expressive (2.10 cr/char)
• "google-neural2" — free plan compatible (0.50 cr/char)

---

Step 4: Your First Image Generation

Image and music generation go through the unified endpoint: POST /api/generate.

curl:

curl -X POST https://sonnalabs.app/api/generate \
  -H "X-API-Key: sona_sk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "IMAGE",
    "model": "nano-banana-2",
    "prompt": "A photorealistic mountain landscape at golden hour, 4K"
  }'

JavaScript:

const response = await fetch("https://sonnalabs.app/api/generate", {
  method: "POST",
  headers: {
    "X-API-Key": "sona_sk_YOUR_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "IMAGE",
    model: "nano-banana-2",
    prompt: "A photorealistic mountain landscape at golden hour, 4K",
  }),
});

const result = await response.json();
console.log(result.imageUrl);

Common image model values for the model field:

model value	Cost	Notes
"qwen-z-image"	70 cr	Budget/fast
"grok-image"	340 cr	Balanced
"nano-banana-2"	680–1,530 cr	High quality
"nano-banana-pro"	1,530–2,035 cr	Maximum quality
"flux-2-pro"	425–595 cr	Artistic
"gpt-image-2"	510–1,360 cr	Instruction-following

---

Step 5: Your First Music Generation

Music generation also uses POST /api/generate with type: "MUSIC":

curl:

curl -X POST https://sonnalabs.app/api/generate \
  -H "X-API-Key: sona_sk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MUSIC",
    "model": "suno-v4_5all",
    "prompt": "Upbeat lo-fi hip hop with piano and rain ambiance"
  }'

JavaScript:

const response = await fetch("https://sonnalabs.app/api/generate", {
  method: "POST",
  headers: {
    "X-API-Key": "sona_sk_YOUR_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "MUSIC",
    model: "suno-v4_5all",
    prompt: "Upbeat lo-fi hip hop with piano and rain ambiance",
  }),
});

const result = await response.json();
console.log(result.audioUrl);

Music generation, like TTS and image, is eligible for the 10% API discount.

---

Step 6: Understanding the Credit System

Every successful generation deducts credits from your balance. Here's how the balance works:

1. Subscription credits are consumed first — your monthly Pro (102,000 cr) or Max (187,000 cr) allocation
2. PAYG credits are used next — if your subscription credits run out, the balance draws from any PAYG top-up you've purchased
3. If both are exhausted, the API returns a credit error and no generation occurs

You can monitor your credit consumption in the Analytics tab of Sonna Console.

PAYG top-up options:

Package	Credits	Price
Starter	62,500 cr	Rp94,000
Plus	125,000 cr	Rp174,000
Creator	250,000 cr	Rp317,000

---

Step 7: The 10% API Discount

Every eligible generation made through the API automatically receives a 10% credit discount. The discount applies to:

• ✅ Text-to-Speech (all models)
• ✅ Image generation (all models)
• ✅ Music generation (all models)
• ❌ Video generation (excluded)

The discount is applied at deduction time — you see the discounted credit amount in the request log and analytics, not the listed rate. There's nothing to configure; it's applied automatically to all API requests.

---

Error Reference

HTTP Status	Meaning
401	Invalid or missing API key
402	Insufficient credits
422	Invalid request body (check required fields)
429	Rate limit exceeded
500	Server error — retry with exponential backoff

---

What's Next

• Browse all available models and their API identifiers in the Models catalog
• Monitor usage and manage keys from the Sonna Console
• Check the full API reference in the developer documentation at docs.sonnalabs.app

The API covers the same capabilities available in the Sonna web app — if you can generate it in the UI, you can automate it through the API.

---

Get your API key at /app/console/api-keys. The full developer documentation is available at docs.sonnalabs.app.