API Reference

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.

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:

Authorization: Bearer YOUR_API_KEY

Or for WebSocket connections, as a query parameter:

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

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

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

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123"
  }
}

Error Responses

{
  "error": "Rate limit exceeded",
  "error_code": "RATE_LIMITED",
  "code": 429
}

Error Codes

See Error Codes 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:

Python SDK

pip install kugelaudio

JavaScript SDK

npm install kugelaudio

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

Get started

Build a voice agent

Generate audio

Voices

Deploy

SDK Reference

API Reference

Base URL

Authentication

Request Format

HTTP Requests

WebSocket Connections

Response Format

Success Responses

Error Responses

Error Codes

Rate Limits

Endpoints Overview

Text-to-Speech

Voices

Models

Usage

SDKs

Python SDK

JavaScript SDK

Versioning

Current Version

Deprecation Policy

​Base URL

​Authentication

​Request Format

​HTTP Requests

​WebSocket Connections

​Response Format

​Success Responses

​Error Responses

​Error Codes

​Rate Limits

​Endpoints Overview

​Text-to-Speech

​Voices

​Models

​Usage

​SDKs

Python SDK

JavaScript SDK

​Versioning

​Current Version

​Deprecation Policy

Base URL

Authentication

Request Format

HTTP Requests

WebSocket Connections

Response Format

Success Responses

Error Responses

Error Codes

Rate Limits

Endpoints Overview

Text-to-Speech

Voices

Models

Usage

SDKs

Versioning

Current Version

Deprecation Policy