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.mp3Hindi 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.mp3Voice 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.mp3Integration 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
| Status | Cause | Solution |
|---|---|---|
| 400 | Text too long or invalid parameters | Keep text under 5,000 characters |
| 401 | Invalid or missing API key | Check your API key is correct and active |
| 402 | Insufficient wallet balance | Top up your thinnestAI wallet |
| 429 | Rate limit exceeded | Wait 60 seconds, or increase your key's rate limit |
| 503 | Inference server unavailable | Retry after a few seconds |