Aero TTS

SDKs & Integration

Integrate Aero TTS into your applications with Python, JavaScript, cURL, and more.

SDKs & Integration

Aero TTS uses a standard REST API. You can integrate it with any programming language that supports HTTP requests.

Python

import requests

API_KEY = "thns_sk_YOUR_KEY"
BASE_URL = "https://api.thinnest.ai/api/tts"

def synthesize(text, voice="aero-vayu", model="aero", format="mp3"):
    response = requests.post(
        f"{BASE_URL}/synthesize",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "text": text,
            "voice": voice,
            "model": model,
            "format": format,
        },
    )
    response.raise_for_status()
    return response.content

# Generate speech
audio = synthesize("Hello from Aero TTS!")

# Save to file
with open("output.mp3", "wb") as f:
    f.write(audio)

# Play immediately (requires playsound package)
# pip install playsound
# from playsound import playsound
# playsound("output.mp3")

Python with Streaming

import requests

def synthesize_stream(text, voice="aero-vayu", callback=None):
    """Stream audio chunks as they are generated."""
    response = requests.post(
        f"{BASE_URL}/synthesize",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "text": text,
            "voice": voice,
            "model": "aero",
            "format": "pcm",
        },
        stream=True,
    )
    response.raise_for_status()

    for chunk in response.iter_content(chunk_size=4096):
        if chunk and callback:
            callback(chunk)

# Example: stream to file
with open("stream.pcm", "wb") as f:
    synthesize_stream(
        "This audio is streamed chunk by chunk.",
        callback=lambda chunk: f.write(chunk),
    )

List Voices in Python

def list_voices(language=None, gender=None):
    params = {}
    if language:
        params["language"] = language
    if gender:
        params["gender"] = gender

    response = requests.get(
        f"{BASE_URL}/voices",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params,
    )
    response.raise_for_status()
    return response.json()["voices"]

# All English (US) female voices
voices = list_voices(language="en-us", gender="female")
for v in voices:
    print(f"{v['voice_id']}: {v['name']}{v['description']}")

JavaScript / Node.js

const API_KEY = "thns_sk_YOUR_KEY";
const BASE_URL = "https://api.thinnest.ai/api/tts";

async function synthesize(text, voice = "aero-vayu", model = "aero") {
  const response = await fetch(`${BASE_URL}/synthesize`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text,
      voice,
      model,
      format: "mp3",
    }),
  });

  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.detail || `Synthesis failed: ${response.status}`);
  }

  return response.arrayBuffer();
}

// Generate and save
const audio = await synthesize("Hello from Aero TTS!");
const fs = await import("fs");
fs.writeFileSync("output.mp3", Buffer.from(audio));

Browser Playback

async function speakText(text, voice = "aero-vayu") {
  const response = await fetch(`${BASE_URL}/synthesize`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text, voice, model: "aero", format: "mp3" }),
  });

  const blob = await response.blob();
  const url = URL.createObjectURL(blob);
  const audio = new Audio(url);
  audio.play();
  audio.onended = () => URL.revokeObjectURL(url);
}

// Usage
speakText("This plays directly in the browser.");

cURL

Basic Synthesis

curl -X POST https://api.thinnest.ai/api/tts/synthesize \
  -H "Authorization: Bearer thns_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "voice": "aero-vayu", "format": "mp3"}' \
  --output hello.mp3

Hindi Voice

curl -X POST https://api.thinnest.ai/api/tts/synthesize \
  -H "Authorization: Bearer thns_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "नमस्ते, आप कैसे हैं?",
    "voice": "aero-ananya",
    "model": "aero",
    "language": "hi",
    "format": "mp3"
  }' \
  --output namaste.mp3

Voice Mix (Inline)

curl -X POST https://api.thinnest.ai/api/tts/synthesize \
  -H "Authorization: Bearer thns_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is a blended voice.",
    "voice": "aero-vayu",
    "model": "aero",
    "voice_mix": [
      {"voice": "aero-vayu", "weight": 1.5},
      {"voice": "aero-aria", "weight": 0.8}
    ],
    "format": "mp3"
  }' \
  --output blended.mp3

Integration with Voice Agents

Aero TTS is automatically used when you select it as the TTS provider for your thinnestAI voice agents. No separate API integration is needed — just set the provider in your agent's voice configuration:

curl -X PATCH https://api.thinnest.ai/agents/agent_abc123 \
  -H "Authorization: Bearer thns_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_config": {
      "tts_provider": "aero",
      "tts_model": "aero",
      "tts_voice_id": "aero-vayu"
    }
  }'

See Voice Configuration for full voice agent setup.

Error Handling

All error responses return JSON with a detail field:

{ "detail": "Rate limit exceeded (100 requests/min). Try again later." }

Common Errors

StatusCauseSolution
400Text too long or invalid parametersKeep text under 5,000 characters
401Invalid or missing API keyCheck your API key is correct and active
402Insufficient wallet balanceTop up your thinnestAI wallet
429Rate limit exceededWait 60 seconds, or increase your key's rate limit
503Inference server unavailableRetry after a few seconds

On this page