Frequently asked questions
Is there an official SDK for this API?
No, there is no official SDK from IVR Switch. You should use the official OpenAI SDKs or plain HTTP requests. The API endpoint shape matches the OpenAI speech endpoint, so you can easily integrate it into your existing codebase by simply adjusting the base URL configuration.
Can I use the Python OpenAI SDK?
Yes, the Python OpenAI SDK works perfectly. You just need to change the base_url to https://api.ek33.info/v1 and provide your API key. This allows you to use the same code structure you are already familiar with, making migration from other providers straightforward and quick.
How do I set the language explicitly?
Include the language field in your JSON request body with the ISO code. If omitted, the system guesses the language, defaulting to English for Latin script. For non-English Latin text, always set this field to ensure accurate pronunciation and avoid misinterpretation by the synthesis engine.
What is the maximum input length?
The maximum input length is 4,096 characters per request. If your text exceeds this limit, you must split it into smaller parts. Each part is processed separately, and you should join the resulting audio files to create the final output for your application or IVR system.
Does the API support streaming audio?
No, the API does not support streaming, WebSockets, or real-time partial audio. It returns the complete audio file in the response. This synchronous approach simplifies integration for call centers and IVR systems that typically handle static audio files rather than real-time streaming audio streams.
Is SSML supported in the input?
No, SSML is not supported. You send plain text in the input field. The API does not offer phoneme dictionaries or custom pronunciation lexicons either. Your text is processed directly, so you cannot use SSML tags to control pauses, emphasis, or pronunciation details within the input.
How do I handle rate limit errors?
You are limited to 60 requests per minute per key. If you exceed this, you will receive an error. Implement exponential backoff in your code to retry requests. For new accounts, the limit is 10 requests per minute until you make your first top-up to increase capacity.
Can I change the voice mid-stream?
Since the API does not support streaming, you cannot change voices mid-stream in a single audio file. To change voices, you must make separate requests for each segment using the desired voice preset. Then, concatenate the resulting audio files in your application logic to create the final output.
Are the audio files downloadable?
Yes, the generated audio is returned directly in the API response. You can save this response to your storage or play it immediately. The audio is not stored on our servers after the response is sent, ensuring your data remains under your control for your specific use case.
How do I generate a new API key?
You can issue a new key at any time from your account dashboard. When you generate a new key, the old one stops working immediately. This allows you to rotate keys securely without downtime. You can manage your keys and view your balance on the /get-api-key/ page.
What happens if the server is down?
We do not provide an SLA or uptime guarantee. If the service is unavailable, your requests will fail. Failed requests are free, so you are not charged for unsuccessful attempts. You can monitor the status and retry your requests once the service is back online.
Is there a WebSocket endpoint?
No, there is no WebSocket endpoint. The API uses standard HTTP POST requests to send text and receive audio files. This RESTful approach is compatible with all standard HTTP clients and SDKs, making it easy to integrate into your existing infrastructure without needing specialized WebSocket handling logic.
Can I send audio in PCM format?
Yes, you can specify pcm as the response_format in your request. Other supported formats include mp3, wav, opus, and flac. Choose the format that best fits your IVR system or application requirements. The API will generate the audio in your specified format and return it in the response.
Do I need to handle chunking manually?
Yes, you must handle chunking manually if your text exceeds 4,096 characters. Split your text into parts, send each part in a separate request, and then join the resulting audio files. The API does not automatically split long texts, so your application logic must manage this process.
First request
curl
curl https://api.ek33.info/v1/audio/speech \
-H "Authorization: Bearer $TTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
--output hello.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.ek33.info/v1", api_key="tts-...")
with client.audio.speech.with_streaming_response.create(
model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
response.stream_to_file("hello.mp3")Node.js (openai)
import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ baseURL: "https://api.ek33.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));| voice | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Authentication
Authentication for the IVR Switch API relies on a simple Bearer token. You must include your unique API key in the HTTP header as Authorization: Bearer tts-your_api_key_here with every request. This key is generated when you create your account on our /get-api-key/ page.
Bearer token format explanation
The token is a string starting with tts- followed by a unique identifier. Ensure you copy the key exactly as shown in your dashboard, including any trailing spaces. The header must be present in every API call to validate your account and track usage against your rate limits.
How to generate a new API key
Navigate to the /get-api-key/ section of this site. You can sign up using Google or an email/password combination. Once logged in, your active API key is displayed on the dashboard alongside your current balance and usage statistics.
Revoking old keys instantly
You can issue a new API key at any time from your dashboard. When you generate a new key, the previous one stops working immediately. This is useful for security or if you suspect a key has been exposed in your client-side code.
- One active key per account
- Old keys stop at once
- Generate new key via dashboard
Base URL Configuration
All API calls route through https://api.ek33.info/v1. The core endpoint for generating audio is POST /v1/audio/speech. This structure mirrors the standard OpenAI speech endpoint, ensuring compatibility with existing integrations.
Endpoint structure for speech
Send your text payload to this POST endpoint. The API accepts JSON bodies with fields like model, input, and voice. Responses return the audio file directly, ready for playback in your IVR or app.
Configuring base_url for SDKs
Update your SDK configuration to point to our base URL: https://api.ek33.info/v1. This single change redirects all requests to our infrastructure while maintaining standard request shapes.
Using official OpenAI SDKs
You can use the official OpenAI SDKs by simply changing the base_url parameter. Pass your unique tts-... API key in the Authorization header, and the SDK handles the rest seamlessly.
Request Parameters
Send your text in the input field, keeping each request under 4,096 characters. For longer scripts, split the text and join the resulting audio files, as requests are processed sequentially. Spaces and punctuation count toward the character limit, so plan your chunks accordingly to stay within bounds.
Input text and character limits
Keep each request under 4,096 characters. For longer scripts, split the text and join the resulting audio files, as requests are processed sequentially.
Voice selection from 8 presets
Choose from eight distinct voices, including female options like Aria and Nova, or male tones like Felix and Atlas. Each voice offers a different character, from warm narration to energetic promos, without requiring custom cloning or additional setup.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Speed control between 0.25 and 4.0
Adjust the speed parameter between 0.25 and 4.0 to fit your IVR timing needs. Faster speeds reduce latency for short prompts, while slower rates improve clarity for complex instructions.
Response Formats
The API returns audio files in multiple formats to suit different integration needs. Choose the format that best matches your client’s capabilities, whether you are building a web app or a legacy telephony system.
MP3 for web compatibility
MP3 is the default and most widely supported format. It offers a good balance between file size and quality, making it ideal for web players and mobile apps.
WAV for telephony integration
WAV files are uncompressed and perfect for IVR systems. They ensure consistent playback quality across different telephony hardware without additional decoding steps.
OPUS and FLAC options
OPUS provides high efficiency, while FLAC offers lossless compression. Use OPUS to save bandwidth or FLAC when archiving high-fidelity audio.
- OPUS: Suitable for bandwidth-constrained environments.
- FLAC: Ideal for archival or editing purposes.
Language Detection
Our API automatically detects the language from the input script. Latin text defaults to English, but you can force any of the 23 supported languages using the optional language parameter. This ensures accurate synthesis for non-English Latin-script text.
Auto-detection from script
The engine analyzes the character set to guess the language. If you send Arabic, Greek, or Cyrillic text, it selects the correct language automatically. This works for all 23 supported languages without extra configuration.
- Supports Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.
Manual language code override
Send an ISO language code (e.g., "language": "fr") in your JSON body. This overrides auto-detection and ensures consistent voice behavior. It is essential when the script looks Latin but should be spoken in another language.
Handling mixed language text
The API does not switch languages mid-sentence. For mixed text, split your input or set the language to the dominant script. Unsupported languages like Vietnamese or Ukrainian are not supported.
- Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, and Bengali are not supported.

Rate Limits and Quotas
Your API key allows up to 60 requests per minute once your account is active. This limit applies to the POST /v1/audio/speech endpoint and ensures fair usage across all customers on the platform.
60 requests per minute standard
After your initial period or first top-up, the rate limit increases to 60 requests per minute. This standard quota supports steady IVR generation without requiring complex batching logic.
10 requests per minute initially
New accounts start with a limit of 10 requests per minute. This lower tier allows you to test voice quality and integration stability before scaling up your call center traffic.
Handling queue delays
Requests are processed sequentially. Under heavy load, a request may wait in a queue before synthesis begins. Longer texts take roughly real-time duration to generate, so plan your concurrency accordingly to avoid timeouts.
- Requests are processed one after another.
- Short phrases take a few seconds.
- Long texts generate at roughly real-time speed.
Error Handling
The API returns standard HTTP status codes to indicate success or failure. A 200 OK means the audio file is ready. Non-200 codes, such as 401 for unauthorized access or 429 for rate limits, signal specific issues that require attention.
Common HTTP error codes
Use 400 Bad Request when input parameters are invalid. A 401 Unauthorized error indicates an incorrect Bearer token. Check your key format and ensure it starts with 'tts-'.
Billing adjustments on failure
If synthesis fails, the charge is returned in full. You are only billed for successful audio generation. Failed requests do not consume your character quota.
Retrying failed requests
Implement exponential backoff for transient errors like 429 Too Many Requests. Since requests are processed sequentially, queue delays may cause temporary timeouts. Wait briefly before retrying to avoid hitting the 60 requests per minute limit.
Code Examples
Start with a simple curl command to verify your key and get audio immediately. This works for any voice, from Aria to Orion, and returns the file directly in your terminal.
Basic curl command example
Use this one-liner to generate speech. Replace YOUR_API_KEY with your token from the dashboard.
curl -X POST "https://api.ek33.info/v1/audio/speech" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"model\": \"tts-1\", \"input\": \"Hello world\", \"voice\": \"nova\"}" \
--output speech.mp3
Python script with OpenAI SDK
Leverage the official OpenAI Python SDK by pointing it to our base URL. This allows you to integrate TTS into your existing Python workflows with minimal code changes.
- import openai
- client = openai.OpenAI(base_url="https://api.ek33.info/v1", api_key="YOUR_API_KEY")
- with client.audio.speech.create(
- model="tts-1", voice="sage", input="Call center greeting"
- ) as response:
- response.write_to_file("out.wav")
Node.js integration snippet
For Node.js environments, use the openai package similarly. Ensure you handle the response stream correctly to write the audio file to disk or pipe it to a server.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Her gentle cadence helps complex information land clearly, reducing the need for callers to ask for repetition during onboarding or support calls.
23 languages
Any voice speaks any of these languages.
