Quick Start
Choose your preferred programming language to get started with the API:
import requests
url = "https://ttsapi.site/v1/audio/speech"
headers = {
"Content-Type": "application/json"
}
data = {
"input": "Hello, this is a test.",
"voice": "alloy",
"instructions": "Speak in a cheerful and upbeat tone." # Optional
}
response = requests.post(url, json=data, headers=headers)
if response.status_code == 200:
# Save the audio file - always MP3 format regardless of Content-Type header
with open("output.mp3", "wb") as f:
f.write(response.content)
print("Audio saved as output.mp3")
else:
print(f"Error: {response.status_code}, {response.json()}")
async function generateSpeech() {
const response = await fetch('https://ttsapi.site/v1/audio/speech', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
input: 'Hello, this is a test.',
voice: 'alloy',
instructions: 'Speak in a cheerful and upbeat tone.' // Optional
})
});
if (response.ok) {
// Always MP3 format regardless of Content-Type header
const blob = await response.blob();
const audio = new Audio(URL.createObjectURL(blob));
audio.play();
} else {
const error = await response.json();
console.error('Error:', error);
}
}
Available Voices
API Reference
Generate Speech (OpenAI Compatible)
POST /v1/audio/speech
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| input | string | Yes | The text to convert to speech |
| voice | string | Yes | The voice to use (see Available Voices) |
| instructions | string | No | Mapped to "prompt" parameter when sent to the backend service. Can be used to guide voice emotion or style. |
| response_format | string | No | OpenAI compatibility only - only changes the Content-Type header but not the actual audio format. May result in incorrect Content-Type headers. Audio is always MP3. |
| model | string | No | OpenAI compatibility only - completely ignored. |
| speed | number | No | OpenAI compatibility only - completely ignored. |
Note: Parameters in gray are completely ignored by the service or may cause misleading behavior. Only input, voice, and instructions affect the actual TTS output.
How the Instructions Parameter Works
The instructions parameter is mapped to a prompt parameter when sent to the backend service. It can be used to guide the voice emotion, tone, or style. Some examples of effective instructions:
- Emotional guidance: "Speak in a happy and excited tone."
- Character impersonation: "Speak like a wise old wizard."
- Contextual hints: "This is being read to a child, speak gently."
- Reading style: "Read this as a news broadcast."
Tip: Keep instructions clear and concise. Overly complex instructions may not be interpreted correctly.
Response Format
The API always returns a binary MP3 audio file with the following headers:
Content-Type: "audio/mpeg"Access-Control-Allow-Origin: "*" (CORS enabled)
Important: While the response_format parameter may change the Content-Type header in the response, it does not actually convert the audio format. The audio is always returned as MP3 from the upstream service.
Error Responses
| Status Code | Description |
|---|---|
| 400 | Missing required parameters (input or voice) |
| 429 | Rate limit exceeded or queue is full. Includes Retry-After header when rate limited. |
| 500 | Internal server error |
Queue System
The API uses a queue system to handle multiple requests efficiently:
- Maximum queue size: Configurable via
MAX_QUEUE_SIZEenvironment variable (default: 100 requests) - Requests are processed in FIFO (First In, First Out) order
- Rate limiting: Configurable via
RATE_LIMIT_REQUESTSandRATE_LIMIT_WINDOWenvironment variables (default: 30 requests per 60 seconds per IP address) - Queue status can be monitored via the
/api/queue-sizeendpoint - Queue status updates every 2 seconds in the web interface
- Visual indicators show queue load (Low/Medium/High) based on utilization
Queue Status Endpoint
GET /api/queue-size
Returns JSON with queue information:
{
"queue_size": 0, // Current number of requests in queue
"max_queue_size": 100 // Maximum queue capacity
}
Response Status Codes
200- Success429- Queue is full or rate limit exceeded500- Server error
Queue Load Indicators
- Low Load (0-40%): Green indicator, optimal for new requests
- Medium Load (40-75%): Yellow/Orange indicator, some delay expected
- High Load (75-100%): Red indicator, significant delay expected