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`

Only the SDKs understand the eu- key prefix. When you call the API directly, use https://api.eu.kugelaudio.com and send the key without the eu- prefix.

Authentication

Send your API key as Authorization: Bearer YOUR_API_KEY (or X-API-Key), or as ?api_key= on WebSocket URLs. GET /v1/models is public; everything else requires a key. See Authentication for all accepted forms and key management.

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

To call the API from a language without an SDK, including WebSocket tooling and text-encoding tips, see Use the API without an SDK.

Requests and responses

HTTP requests send JSON (Content-Type: application/json); WebSocket messages are JSON frames over wss://. Success bodies are endpoint-specific: catalog endpoints return JSON, synthesis endpoints return binary audio or WebSocket JSON frames. Errors share one shape:

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

See Error Codes for every status, error_code, and WebSocket close code. Rate-limit errors are 429 RATE_LIMITED, with a Retry-After header when retry timing is available.

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)

Speech-to-Text

Endpoint	Method	Description
`/v1/audio/transcriptions`	POST	Transcribe a complete audio upload
`/v1/audio/transcriptions/stream`	WebSocket	Stream PCM16 and receive revisable partials plus a corrected final

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}/avatar`	PUT	Upload an avatar image for an owned voice
`/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

Java SDK

com.kugelaudio:kugelaudio

Versioning

Public REST resources and the speech-to-text stream use the /v1/ URL prefix (/v1/audio/transcriptions/stream). The text-to-speech WebSocket routes are under /ws/tts.

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

Base URL

Authentication

Requests and responses

Endpoints Overview

Text-to-Speech

Speech-to-Text

Voices

Models

Dictionaries

Usage

SDKs

Python SDK

JavaScript SDK

Java SDK

Versioning

​Base URL

​Authentication

​Requests and responses

​Endpoints Overview

​Text-to-Speech

​Speech-to-Text

​Voices

​Models

​Dictionaries

​Usage

​SDKs

Python SDK

JavaScript SDK

Java SDK

​Versioning

Base URL

Authentication

Requests and responses

Endpoints Overview

Text-to-Speech

Speech-to-Text

Voices

Models

Dictionaries

Usage

SDKs

Versioning