Text-to-Speech API

Welcome to Suonora’s Text-to-Speech (TTS) API! Our service converts written text into high-quality, natural-sounding speech. This documentation outlines everything you need to know about authenticating requests, configuring parameters, handling errors, and more.

Overview

Suonora TTS empowers you to create dynamic audio experiences directly from plain text. Whether you’re building an IVR system, integrating with a chatbot, or enhancing user accessibility, our API delivers rich, studio-grade speech.

Key Features

High-Quality Audio
Voices are carefully tuned and tested to sound as natural and lifelike as possible.
Direct Audio Streaming
Responses stream raw MP3 or OGG audio — no Base64 encoding.
Voice Customization
Modify pitch, emotion, and style. Choose from multiple speaking styles like cheerful, calm, angry, and more.
Multilingual Support
Over 90 languages and dialects. Simply choose the right voice and lang to target your audience.

Authentication

All requests must include a valid API key.

Bearer Token: Send your API key in the Authorization header.
Use HTTPS: Always use https:// to protect your API key in transit.

Example

curl https://api.suonora.com/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Quickstart

Here’s how to send a TTS request and get back raw audio data.

curl -X POST https://api.suonora.com/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --output output.mp3 \
  -d '{
    "input": "Welcome to Suonora TTS!",
    "model": "legacy-v2.5",
    "voice": "axel"
  }'

Tip: --output output.mp3 saves the response audio directly into a file.

API Reference

Generate Speech `POST /v1/audio/speech`

HTTP Request

POST https://api.suonora.com/v1/audio/speech

Headers

Header	Value
Authorization	`Bearer YOUR_API_KEY`
Content-Type	`application/json`

Request Body

Parameter	Type	Required	Default	Description
`input`	string	Yes	-	The text to be synthesized (up to 5,000 characters).
`model`	string	Yes	-	Name of the synthesis model (e.g., `legacy-v2.5`).
`voice`	string	Yes	-	Voice ID from our Voice Gallery (opens in a new tab).
`pitch`	string	No	`+0%`	Pitch adjustment from `-100%` (lowest) to `+100%` (highest).
`style`	string	No	`calm`	Emotional speaking style: `neutral`, `cheerful`, `calm`, `angry`, `sad`, `excited`, `whispering`.
`styleDegree`	number	No	`1.5`	Intensity of the selected style. Range from `0.5` (subtle) to `2.0` (dramatic).
`lang`	string	No	`en-US`	A BCP-47 language code (e.g., `fr-FR`, `ja-JP`). Typically aligns with the voice to ensure optimal pronunciation.

Response

Content-Type: audio/mpeg
Body: Raw binary audio (MP3 format)

Usage Examples

Node.js Example

javascript

import { writeFile } from "fs/promises";
import fetch from "node-fetch";
 
async function generateAudio() {
  const response = await fetch("https://api.suonora.com/v1/audio/speech", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      input: "Today's weather is sunny and clear.",
      model: "legacy-v2.5",
      voice: "axel"
    }),
  });
 
  if (!response.ok) {
    throw new Error("TTS generation failed");
  }
 
  const audioBuffer = await response.arrayBuffer();
  await writeFile("weather.mp3", Buffer.from(audioBuffer));
  console.log("Audio saved as weather.mp3");
}
 
generateAudio().catch(console.error);

Web Browser Example (HTML)

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Suonora TTS Example</title>
</head>
<body>
  <button onclick="playAudio()">Generate & Play Audio</button>
  <audio id="tts-player" controls></audio>
 
  <script>
    async function playAudio() {
      const response = await fetch("https://api.suonora.com/v1/audio/speech", {
        method: "POST",
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          input: "Hello from Suonora!",
          model: "legacy-v2.5",
          voice: "axel"
        }),
      });
 
      if (!response.ok) {
        alert("TTS request failed");
        return;
      }
 
      const blob = await response.blob();
      const audioUrl = URL.createObjectURL(blob);
      document.getElementById("tts-player").src = audioUrl;
    }
  </script>
</body>
</html>

✅ Now using blob — no Base64.

Error Handling

HTTP Status	Error Type	Description	Suggested Resolution
400	Invalid Parameters	Missing fields or malformed request body.	- Ensure `input`, `model`, and `voice` are properly set.
401	Unauthorized	Invalid or missing API key.	- Verify your API key is valid and properly included.
429	Rate Limit Exceeded	Too many requests.	- Implement retry logic with exponential backoff.
500	Internal Server Error	An unexpected error occurred on the server.	- Retry after a few seconds. If it persists, contact support.

Best Practices

Match voice and language (lang with voice).
Chunk large texts if input exceeds 5,000 characters.
Retry 5xx errors with exponential backoff.
Cache generated audio when appropriate.
Keep API keys secret.

FAQ

Q: What audio formats are supported?
A: MP3 currently. OGG and WAV coming soon.

Q: Is Base64 output still available?
A: No. Suonora now streams raw audio directly for better performance.

Q: Can I use Suonora TTS offline?
A: No. Suonora requires an active internet connection.

Changelog

v1.0.0 – Initial Release (Base64 encoded audio)
v1.2.0 – April 2025
New Endpoint: /v1/audio/speech
No more Base64 output — raw MP3 audio streamed directly
New input parameters: input, model, voice (plus optional: pitch, style, styleDegree, lang)

Balance Endpoint Voices Endpoint