Skip to main content
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.
SelectionBase URL
Defaulthttps://api.kugelaudio.com
Direct EUhttps://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

EndpointMethodDescription
/v1/tts/generatePOSTGenerate speech from text
/ws/ttsWebSocketStream audio generation
/ws/tts/streamWebSocketStream text input, stream audio output
/ws/tts/multiWebSocketMulti-context streaming (up to 20 concurrent streams)

​
Voices

EndpointMethodDescription
/v1/voicesGETList available voices
/v1/voices/{id}GETGet voice details

​
Models

EndpointMethodDescription
/v1/modelsGETList available models

​
Usage

EndpointMethodDescription
/v1/usageGETGet current usage
/v1/usage/historyGETGet 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