API Reference
KugelAudio API reference overview: base URL, authentication, request and response format, and an index of the text-to-speech, voice and model endpoints.
On this page
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.comThis 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.
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
The REST endpoints below are also described by the OpenAPI document, for client generators and API tools.
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 an authoritative final per turn |
See Speech to Text; these two endpoints are not in the OpenAPI document.
Speech-to-Speech
| Endpoint | Method | Description |
|---|---|---|
/v1/live/sessions | WebSocket | Hold a live voice conversation with fluid-1 |
See Speech to Speech; this endpoint is not in the OpenAPI document.
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:
Versioning
Public REST resources use the /v1/ URL prefix. The text-to-speech WebSocket
routes are under /ws/tts.
The speech-to-text stream uses the /v1/ prefix too:
/v1/audio/transcriptions/stream.