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
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/json
- Accept:
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_request | Request validation failed |
| 401 | unauthorized | Invalid or missing API key |
| 403 | forbidden | API key lacks permission |
| 404 | not_found | Resource not found |
| 429 | rate_limited | Too many requests |
| 402 | insufficient_credits | Not enough credits |
| 500 | internal_error | Server error |
Rate Limits
| Plan | Requests/min | Concurrent Streams |
|---|
| Free | 10 | 1 |
| Starter | 60 | 3 |
| Business | 300 | 10 |
| Enterprise | 1000 | 50 |
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000
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 5 concurrent streams) |
Voices
| Endpoint | Method | Description |
|---|
/v1/voices | GET | List available voices |
/v1/voices/{id} | GET | Get voice details |
Models
| Endpoint | Method | Description |
|---|
/v1/models | GET | List available models |
Usage
| Endpoint | Method | Description |
|---|
/v1/usage | GET | Get current usage |
/v1/usage/history | GET | Get usage history |
SDKs
We provide official SDKs for easy integration:
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
