> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> 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.

```bash theme={null}
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](/docs/aero-tts/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

```bash theme={null}
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

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

### Example

```bash theme={null}
# 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

```json theme={null}
{
  "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": 10 }
  ]
}
```

***

## List Models

Get available Aero TTS models with specs.

```
GET /api/tts/models
```

### Response

```json theme={null}
{
  "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

```json theme={null}
{ "status": "ok", "server_status": 200 }
```

If the server is down:

```json theme={null}
{ "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
```

```json theme={null}
{
  "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
```

```json theme={null}
{
  "name": "Production Key",
  "rate_limit": 100
}
```

**Response:**

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.