Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or email plus password. Accounts are per site. The dashboard displays your active key, balance, and usage statistics immediately after registration.
What is the base URL for the API?
The API base URL is https://api.sotmal.info/v1. You send POST requests to https://api.sotmal.info/v1/audio/speech. This endpoint accepts JSON bodies containing your text, voice selection, and format preferences.
Can I use the OpenAI SDK?
Yes. The request shape matches the OpenAI speech endpoint. Configure your SDK’s base_url to https://api.sotmal.info/v1 and use your site’s key. The official OpenAI SDKs work directly with this configuration.
What formats are supported?
Supported response formats are mp3, wav, opus, flac, and pcm. Select the format in your request body. MP3 and WAV are common for IVR systems, while Opus offers efficient compression for bandwidth-limited connections.
How many characters can I send?
Each request supports up to 4096 characters in the input field. For longer texts, split the content into parts of this size. Generate audio for each part and join the resulting files.
What happens if I exceed rate limits?
The limit is 60 requests per minute per key (10 before the first top-up). Exceeding this causes requests to queue or fail. Failed requests are free, so you are not charged for rejected attempts.
Is the API compatible with IVR systems?
Yes. The API generates standard audio files like MP3 or WAV. You can fetch these files and play them in your IVR platform. Typical speed is roughly real-time on long texts, supporting high-volume call routing.
How do I rotate my API key?
You can issue a new key at any time from your dashboard. The old key stops working immediately. This ensures secure access management without downtime, as only one key is active per account.
What is the authentication header?
Use the header: Authorization: Bearer tts-... where ... is your unique key. This key is generated upon account creation or rotation. Include it in every request to authenticate your API calls.
Can I generate multiple voices?
Yes, choose from eight presets: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, or Orion. Each voice supports all 23 languages. Select the desired voice in the request body to vary your IVR menu options.
Is there a sandbox environment?
No. There is no separate sandbox. You use the production API endpoint. You receive $0.50 trial credit (about 50,000 characters) valid for 7 days when signing in with Google. Accounts created with email and password start without trial credit.
How do I handle errors?
Check the HTTP status code in the response. If synthesis fails, the charge is returned in full. Failed requests do not consume your character balance. Review the error details to correct input or format issues.
What is the model name?
Use model 'tts-1' or 'tts-1-hd'. Both use the same engine and price. Select the model in your request body. The choice does not affect pricing, which is $0.01 per 1,000 characters.
Do I need to install additional libraries?
No. You can use plain HTTP requests or the OpenAI SDK. No custom SDK or mobile library is required. Any HTTP client capable of sending JSON POST requests works with this API.
First request
curl
curl https://api.sotmal.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.sotmal.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.sotmal.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
Access the IVR TTS API using a single Bearer token generated via your account dashboard. Authenticate every request by including the header Authorization: Bearer tts-... in your JSON payload.
API Key Generation
Sign in via /get-api-key/ to view your active key, balance, and usage stats. Each account holds one active key at a time, ensuring clear audit trails for call center billing.
Bearer Token Usage
Include the key in the Authorization header for all endpoints. The token grants access to speech generation, voice listings, and model details without requiring additional session management.
Key Rotation Policy
Issue a new key from the dashboard at any time. The previous key stops working immediately, allowing instant revocation if a specific IVR node is compromised.
Endpoints Overview
The API provides three primary endpoints for IVR integration. The speech generation endpoint accepts text and returns audio files, while the voices and models endpoints expose configuration details and available presets without generating audio.
Speech Generation Endpoint
POST /v1/audio/speech accepts a JSON body with model, input text, voice, and format parameters. It returns the synthesized audio file directly in the response body, allowing your IVR system to save the audio for call routing.
- Endpoint: POST https://api.sotmal.info/v1/audio/speech
- Accepts JSON body with text up to 4096 characters
- Returns audio file in specified format (mp3, wav, opus, flac, pcm)
Voices List Endpoint
GET /v1/voices returns a list of available voice presets, their associated languages, supported formats, and pricing information. This allows your system to dynamically select appropriate voices based on the caller's language preference or IVR menu structure.
- Endpoint: GET https://api.sotmal.info/v1/voices
- Returns 8 voice presets (4 female, 4 male)
- Includes language support and format compatibility data
Models Endpoint
GET /v1/models lists the available TTS models, currently including 'tts-1' and 'tts-1-hd'. Both models use the same engine and pricing, allowing you to choose based on quality preferences without cost variation.
- Endpoint: GET https://api.sotmal.info/v1/models
- Lists 'tts-1' and 'tts-1-hd' models
- Both models share identical pricing and engine
Request Parameters
Configure your API requests with precision to ensure optimal audio quality and cost efficiency. The model field accepts either tts-1 or tts-1-hd, both utilizing the same underlying engine and pricing structure, allowing you to switch based on latency requirements without affecting your bill.
Model Selection
Both tts-1 and tts-1-hd use the same engine and pricing, though tts-1-hd is the high-definition variant. Choose tts-1-hd for high-definition audio, noting that the price remains $10 per 1 million characters regardless of the model selected.
Input Text Limits
Each request supports up to 4096 characters, including spaces and punctuation. For longer scripts, split the text into chunks and join the resulting audio files. Generation speed is roughly real-time, so plan your queue logic accordingly for high-volume call routing scenarios.
- Max 4096 characters per request
- Spaces and punctuation count
- Split and join for longer texts
Voice Selection
Select from 8 presets tailored for different IVR tones, from the warm narrator aria to the deep documentary voice orion. All voices support 23 languages; if language is omitted, Latin script defaults to English. Explicitly set the language parameter for non-English Latin text to ensure correct pronunciation.
- 8 voice presets available
- Supports 23 languages
- Latin script defaults to English
Response Formats
The API supports five distinct audio formats, allowing you to optimize bandwidth and playback compatibility for your IVR system. Each format serves a specific technical need, from universal playback to high-fidelity archiving.
MP3 Output
MP3 is a common format for IVR delivery. It provides excellent compression with minimal quality loss, reducing bandwidth costs during high-volume call routing.
- Default output format
- Optimal for narrowband IVR lines
- Smallest file size for faster playback
WAV Output
WAV offers uncompressed, lossless audio. Use this format if your telephony provider requires specific PCM parameters or if you need pristine audio quality for quality assurance audits.
- Uncompressed PCM audio
- Larger file size
- Ideal for QA and archival
Other Formats (OPUS, FLAC, PCM)
OPUS provides superior compression for low-bandwidth networks, while FLAC offers lossless compression for storage efficiency. PCM returns raw audio data, suitable for direct hardware integration or custom processing pipelines.
- OPUS: High efficiency, low bandwidth
- FLAC: Lossless compression
- PCM: Raw audio data
Curl Example
Use curl to verify connectivity and pricing before integrating into your IVR pipeline. This example demonstrates a standard synchronous request for English text using the default voice.
Proper header configuration ensures your API key is authenticated correctly. Understanding error responses helps you handle failures gracefully without wasting call center credits.
Basic Request
Send a POST request to the speech endpoint with your text payload. The API returns the audio file directly in the response body.
Headers Configuration
Include your API key in the Authorization header using the Bearer scheme. Set the Content-Type to application/json to ensure proper parsing of your request body.
- Authorization: Bearer tts-your-api-key
- Content-Type: application/json
Error Handling
Check for HTTP 400 errors if your text exceeds 4096 characters or uses an invalid voice ID. A 401 status indicates an expired or incorrect API key, requiring immediate rotation.
- 400: Invalid parameters or text length
- 401: Unauthorized access
- 429: Rate limit exceeded (60 req/min)

OpenAI SDK Integration
The API mirrors the OpenAI speech endpoint structure, allowing teams to reuse existing integration logic with minimal adjustments. By pointing the client to our base URL, you leverage familiar SDK methods for IVR audio generation without rewriting core request handling.
Base URL Configuration
Set the base_url to https://api.sotmal.info/v1 in your OpenAI SDK client configuration. This directs all requests to our infrastructure while maintaining compatibility with standard OpenAI request shapes.
Client Initialization
Initialize the client using your API key (Bearer token). Ensure the key is passed in the Authorization header. The SDK handles JSON serialization for the model, input, voice, and response_format parameters automatically.
Audio Retrieval
The SDK returns the audio file directly in the response body. For IVR systems, consume the binary response to play the audio. The returned file matches the requested response_format, such as MP3 or WAV, ready for playback in your call routing logic.
Rate Limits
Rate limits govern how quickly your IVR system can request audio synthesis. Understanding these constraints ensures smooth call routing without unnecessary delays or failed prompts.
Limits vary based on your account status and payment history. New accounts start with stricter thresholds, while funded accounts enjoy higher throughput.
Requests per Minute
Each API key is limited to 60 requests per minute once your account is funded. This limit applies per key, so multiple keys can scale your throughput linearly.
Pre-Payment Limits
Accounts without a top-up are restricted to 10 requests per minute. This lower threshold helps manage load for trial users and prevents accidental overuse before payment.
Queue Behavior
Requests are processed one after another. Under load, a request may wait in a queue. Requests are processed one after another, so under load a request may wait in a queue.
- Sequential processing ensures order integrity for multi-line IVR flows.
Error Codes
Errors follow standard HTTP conventions, allowing your IVR system to handle failures gracefully without hanging the caller. Understanding these codes ensures your call flow remains robust during high-volume routing scenarios.
400 Bad Request
Returned when input text exceeds the 4,096 character limit or contains invalid JSON structure. Ensure your script splits long texts before sending requests to avoid silent truncation or parsing errors.
401 Unauthorized
Occurs if the Authorization: Bearer header is missing or contains an invalid key. Verify that your API key starts with tts- and has not been revoked due to rotation.
429 Too Many Requests
Triggered when you exceed 60 requests per minute (or 10 per minute before top-up). Implement retry logic in your IVR logic to handle rate limits.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. For longer scripts, split the text into parts, generate audio files, and join them programmatically.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- IETF RFC 7845: Ogg Opus
- LibriTTS-R corpus (OpenSLR 141)
- openai-python on GitHub
- LibriTTS-R paper (arXiv 2305.18802)
- Creative Commons Attribution 4.0
- LibriVox public-domain audiobooks
- W3C WAI: making audio and video accessible
- openai-node on GitHub
- curl documentation
- MDN: Web Speech API
- ISO 639 language codes
