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

# API Reference

> Complete API documentation for KugelAudio

The KugelAudio API provides programmatic access to our text-to-speech services. This reference documents all available endpoints, request/response formats, and authentication.

## Base URL

All API requests should be made to:

```
https://api.kugelaudio.com
```

This is the canonical geo-routed endpoint. For the direct EU endpoint, see
[Regions](/guides/regions).

| Selection | Base URL                        |
| --------- | ------------------------------- |
| Default   | `https://api.kugelaudio.com`    |
| Direct EU | `https://api.eu.kugelaudio.com` |

## Authentication

All API requests require authentication using an API key. Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Or for WebSocket connections, as a query parameter:

```
wss://api.kugelaudio.com/ws/tts?api_key=YOUR_API_KEY
```

<Warning>
  Keep your API key secret! Never expose it in client-side code or public repositories.
</Warning>

## Request Format

### HTTP Requests

* **Content-Type:** `application/json`
* **Accept:** `application/json` or `audio/*` for TTS endpoints

### WebSocket Connections

* **Protocol:** WebSocket (wss\://)
* **Messages:** JSON-encoded

## Response Format

### Success Responses

```json theme={null}
{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123"
  }
}
```

### Error Responses

```json theme={null}
{
  "error": "Rate limit exceeded",
  "error_code": "RATE_LIMITED",
  "code": 429
}
```

## Error Codes

See [Error Codes](/api-reference/errors) for the full lookup table, including
HTTP status codes, `error_code` values, client-facing messages, and WebSocket
close codes.

## Rate Limits

Rate limit errors use `error_code: "RATE_LIMITED"` and HTTP status `429`.
If retry timing is available, it is sent as the HTTP `Retry-After` header.

## Endpoints Overview

### Text-to-Speech

| Endpoint           | Method    | Description                                           |
| ------------------ | --------- | ----------------------------------------------------- |
| `/v1/tts/generate` | POST      | Generate speech from text                             |
| `/ws/tts`          | WebSocket | Stream audio generation                               |
| `/ws/tts/stream`   | WebSocket | Stream text input, stream audio output                |
| `/ws/tts/multi`    | WebSocket | Multi-context streaming (up to 20 concurrent streams) |

### Voices

| Endpoint          | Method | Description           |
| ----------------- | ------ | --------------------- |
| `/v1/voices`      | GET    | List available voices |
| `/v1/voices/{id}` | GET    | Get voice details     |

### Models

| Endpoint     | Method | Description           |
| ------------ | ------ | --------------------- |
| `/v1/models` | GET    | List available models |

### Usage

| Endpoint            | Method | Description       |
| ------------------- | ------ | ----------------- |
| `/v1/usage`         | GET    | Get current usage |
| `/v1/usage/history` | GET    | Get usage history |

## SDKs

We provide official SDKs for easy integration:

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/sdks/python/quickstart">
    pip install kugelaudio
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript/quickstart">
    npm install kugelaudio
  </Card>
</CardGroup>

## Versioning

The API is versioned via URL path (`/v1/`). We maintain backward compatibility within major versions.

### Current Version

**v1** - Stable, recommended for production use.

### Deprecation Policy

* Deprecated features are announced 6 months in advance
* Deprecated endpoints continue working for 12 months
* Breaking changes only in major version updates