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
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.
HTTP Requests
Content-Type: application/jsonAccept: application/json or audio/* for TTS endpoints
WebSocket Connections
Protocol: WebSocket (wss://)Messages: JSON-encoded
Success Responses { "data" : { ... }, "meta" : { "request_id" : "req_abc123" } }
Error Responses { "error" : { "code" : "invalid_request" , "message" : "Text is required" , "details" : { ... } }, "meta" : { "request_id" : "req_abc123" } }
Error Codes HTTP Status Code Description 400 invalid_requestRequest validation failed 401 unauthorizedInvalid or missing API key 403 forbiddenAPI key lacks permission 404 not_foundResource not found 429 rate_limitedToo many requests 402 insufficient_creditsNot enough credits 500 internal_errorServer error
Rate Limits Plan Requests/min Concurrent Streams Free 10 1 Starter 60 3 Business 300 10 Enterprise 1000 50
Rate limit headers are included in all responses:
X-RateLimit-Limit: 60 X-RateLimit-Remaining: 45 X-RateLimit-Reset: 1640000000
Endpoints Overview Text-to-Speech Endpoint Method Description /v1/tts/generatePOST Generate speech from text /ws/ttsWebSocket Stream audio generation /ws/tts/streamWebSocket Stream text input, stream audio output /ws/tts/multiWebSocket Multi-context streaming (up to 5 concurrent streams)
Voices Endpoint Method Description /v1/voicesGET List available voices /v1/voices/{id}GET Get voice details
Models Endpoint Method Description /v1/modelsGET List available models
Usage Endpoint Method Description /v1/usageGET Get current usage /v1/usage/historyGET Get 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
