Complete REST API reference for Aero TTS — synthesize speech, list voices, manage API keys, and track usage.

Aero TTS API Reference

Base URL: https://api.thinnest.ai/api/tts

All endpoints require a Bearer token — either a thns_sk_* API key or a JWT from the dashboard.

Authorization: Bearer YOUR_API_KEY

Synthesize Speech

Convert text to audio.

POST /api/tts/synthesize

Request Body

Field	Type	Required	Default	Description
`text`	string	Yes	—	Text to synthesize (1-5000 characters)
`voice`	string	No	`aero-vayu`	Voice ID
`model`	string	No	`aero`	Model: `aero`, `aero-mini`, `aero-nano`
`language`	string	No	`en-us`	Language code
`speed`	number	No	1.0	Speed multiplier (0.5-2.0)
`format`	string	No	`mp3`	Output format: mp3, wav, pcm, opus, ogg, flac, aac
`sample_rate`	integer	No	22050	Sample rate in Hz
`voice_mix`	array	No	—	Voice blend config (see Voice Lab)
`source`	string	No	`api`	Source identifier: `api` or `playground`

Response

Returns audio bytes with the following headers:

Header	Description
`X-Aero-Latency-Ms`	Total request latency in milliseconds
`X-Aero-Synthesis-Ms`	Synthesis-only time in milliseconds
`X-Aero-Model-Load-Ms`	Model loading time (0 if cached)
`X-Aero-Audio-Duration`	Audio duration in seconds
`X-Aero-Characters`	Number of characters synthesized
`X-Aero-Model`	Model used for synthesis

Example

curl -X POST https://api.thinnest.ai/api/tts/synthesize \
  -H "Authorization: Bearer thns_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to Aero TTS. This is a demo of our text-to-speech engine.",
    "voice": "aero-vayu",
    "model": "aero",
    "language": "en-us",
    "speed": 1.0,
    "format": "mp3"
  }' \
  --output output.mp3

Error Responses

Status	Description
400	Invalid request (text too long, invalid voice, etc.)
401	Missing or invalid API key
402	Insufficient balance
429	Rate limit exceeded
503	Inference server unavailable

List Voices

Get all available voices with optional filtering.

GET /api/tts/voices

Query Parameters

Parameter	Type	Description
`language`	string	Filter by language code (e.g., `en-us`, `hi`)
`gender`	string	Filter by gender (`male` or `female`)

Response

{
  "voices": [
    {
      "voice_id": "aero-vayu",
      "name": "Vayu",
      "language": "en-us",
      "language_name": "English (US)",
      "gender": "female",
      "description": "Warm, professional",
      "type": "builtin",
      "model": "aero"
    }
  ]
}

Example

# All voices
curl https://api.thinnest.ai/api/tts/voices \
  -H "Authorization: Bearer thns_sk_YOUR_KEY"

# Hindi voices only
curl "https://api.thinnest.ai/api/tts/voices?language=hi" \
  -H "Authorization: Bearer thns_sk_YOUR_KEY"

# Male English voices
curl "https://api.thinnest.ai/api/tts/voices?language=en-us&gender=male" \
  -H "Authorization: Bearer thns_sk_YOUR_KEY"

List Languages

Get all supported languages with voice counts.

GET /api/tts/languages

Response

{
  "languages": [
    { "code": "en-us", "name": "English (US)", "voice_count": 19 },
    { "code": "en-gb", "name": "English (UK)", "voice_count": 8 },
    { "code": "hi", "name": "Hindi", "voice_count": 4 }
  ]
}

List Models

Get available Aero TTS models with specs.

GET /api/tts/models

Response

{
  "models": [
    {
      "id": "aero",
      "name": "Aero",
      "description": "Highest quality, lowest latency",
      "voices": 31
    }
  ]
}

Health Check

Check if the Aero TTS inference server is operational.

GET /api/tts/health

Response

{ "status": "ok", "server_status": 200 }

If the server is down:

{ "status": "unavailable", "error": "Inference server not reachable." }

Voice Mixes

Create Voice Mix

Blend 2-4 voices to create a custom hybrid voice.

POST /api/tts/voice-mixes

{
  "name": "My Custom Voice",
  "voices": [
    { "voice": "aero-vayu", "weight": 1.5 },
    { "voice": "aero-aria", "weight": 0.8 }
  ],
  "description": "A blend of Vayu and Aria"
}

List Voice Mixes

GET /api/tts/voice-mixes

Delete Voice Mix

DELETE /api/tts/voice-mixes/{mix_id}

API Keys

Create API Key

POST /api/tts/api-keys

{
  "name": "Production Key",
  "rate_limit": 100
}

Response:

{
  "api_key": "thns_sk_abc123...",
  "id": 1,
  "key_prefix": "thns_sk_abc",
  "name": "Production Key",
  "rate_limit": 100,
  "scopes": ["tts"],
  "is_active": true,
  "created_at": "2026-03-07T10:00:00Z"
}

Save the api_key value immediately — it is only shown once.

List API Keys

GET /api/tts/api-keys

Delete API Key

DELETE /api/tts/api-keys/{key_id}

Usage

Track your TTS usage over time.

GET /api/tts/usage?period=month

Query Parameters

Parameter	Values	Default
`period`	`day`, `week`, `month`	`month`

Response

{
  "period": "month",
  "summary": {
    "total_characters": 125000,
    "total_requests": 450,
    "avg_latency_ms": 95
  },
  "top_voices": [
    { "voice_id": "aero-vayu", "requests": 200, "characters": 50000 }
  ],
  "top_languages": [
    { "language": "en-us", "requests": 380, "characters": 100000 }
  ],
  "by_model": [
    { "model": "aero", "requests": 400, "characters": 110000 }
  ],
  "daily": [
    { "date": "2026-03-01", "characters": 5000, "requests": 20 }
  ]
}

Pricing

Get current pricing tiers.

GET /api/tts/pricing

Response

{
  "tiers": [
    {
      "tier": "free",
      "display_name": "Free",
      "rate_per_million_chars": 0,
      "monthly_free_chars": 10000,
      "max_requests_per_min": 10,
      "max_chars_per_request": 1000,
      "features": { "voice_mix": false, "streaming": false }
    }
  ]
}

Rate Limits

Rate limits are per API key and configurable (default: 100 requests/minute).

Header	Description
`Retry-After`	Seconds to wait before retrying (on 429)

If you exceed your rate limit, you receive a 429 response:

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

To increase your rate limit, create a new API key with a higher limit or contact support.

WebSocket Streaming

For real-time streaming synthesis, connect to the WebSocket endpoint:

ws://api.thinnest.ai/api/tts/stream

Send a JSON message with the same fields as the synthesize endpoint. Audio chunks are streamed back as binary frames as they are generated.

This is ideal for voice agents where you need to start playback before the full audio is ready.

API Reference

On this page