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

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

Authorization: Bearer YOUR_API_KEY

The native API also accepts X-API-Key: YOUR_API_KEY. Health checks and GET /v1/models are public; synthesis, voice, and dictionary endpoints require authentication. See Authentication for the exact forms and key-management guidance. 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

Success bodies are endpoint-specific. Catalog endpoints return JSON objects, voice-reference listing returns a JSON array, and synthesis endpoints return binary audio or WebSocket JSON frames. See the endpoint page for the exact shape.

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
`/v1/voices`	POST	Create a voice, optionally with reference audio
`/v1/voices/{id}`	PATCH / DELETE	Update or archive an owned voice
`/v1/voices/{id}/references`	GET / POST	List or upload reference audio
`/v1/voices/{id}/references/{ref_id}`	DELETE	Delete reference audio
`/v1/voices/{id}/publish`	POST	Request publication of an owned voice
`/v1/voices/{id}/generate-sample`	POST	Generate a sample for an owned voice

Models

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

Dictionaries

Endpoint	Method	Description
`/v1/dictionaries`	GET / POST	List or create project dictionaries
`/v1/dictionaries/{id}`	GET / PATCH / DELETE	Read, update, or delete a dictionary
`/v1/dictionaries/{id}/entries`	GET / POST / PUT	List, add, or replace dictionary entries
`/v1/dictionaries/{id}/entries/{entry_id}`	PATCH / DELETE	Update or delete one entry

Usage

There is no usage REST endpoint. Per-session usage — audio seconds and the amount charged — is delivered inline on the streaming surfaces as the usage block of the terminal frame (see Stream and Multi-context, or session.lastUsage / getLastUsage() in the SDKs). Account-level totals and history live in the dashboard.

SDKs

We provide official SDKs for easy integration:

Python SDK

pip install kugelaudio

JavaScript SDK

npm install kugelaudio

Versioning

Public REST resources use the /v1/ URL prefix. WebSocket routes are exposed under /ws/tts.

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

Dictionaries

Usage

SDKs

Python SDK

JavaScript SDK

Versioning

​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

​Dictionaries

​Usage

​SDKs

Python SDK

JavaScript SDK

​Versioning

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

Dictionaries

Usage

SDKs

Versioning