Skip to content
KugelAudioDocs

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:

Text
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

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:

JSON
{
  "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

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)

Speech-to-Text

EndpointMethodDescription
/v1/audio/transcriptionsPOSTTranscribe a complete audio upload
/v1/audio/transcriptions/streamWebSocketStream 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

EndpointMethodDescription
/v1/live/sessionsWebSocketHold a live voice conversation with fluid-1

See Speech to Speech; this endpoint is not in the OpenAPI document.

Voices

EndpointMethodDescription
/v1/voicesGETList available voices
/v1/voices/{id}GETGet voice details
/v1/voicesPOSTCreate a voice, optionally with reference audio
/v1/voices/{id}PATCH / DELETEUpdate or archive an owned voice
/v1/voices/{id}/referencesGET / POSTList or upload reference audio
/v1/voices/{id}/references/{ref_id}DELETEDelete reference audio
/v1/voices/{id}/avatarPUTUpload an avatar image for an owned voice
/v1/voices/{id}/publishPOSTRequest publication of an owned voice
/v1/voices/{id}/generate-samplePOSTGenerate a sample for an owned voice

Models

EndpointMethodDescription
/v1/modelsGETList available models

Dictionaries

EndpointMethodDescription
/v1/dictionariesGET / POSTList or create project dictionaries
/v1/dictionaries/{id}GET / PATCH / DELETERead, update, or delete a dictionary
/v1/dictionaries/{id}/entriesGET / POST / PUTList, add, or replace dictionary entries
/v1/dictionaries/{id}/entries/{entry_id}PATCH / DELETEUpdate 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.