Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.mtown.info/v1. You can use the official OpenAI SDKs by changing the base_url to this endpoint. All requests must be sent to https://api.mtown.info/v1/audio/speech for speech synthesis.
How do I generate an API key?
Sign up on https://mtown.info/get-api-key/ using Google or email. The dashboard displays your active Bearer key. You can issue a new key at any time; the previous key stops immediately. Each account has one active key.
Can I use the OpenAI SDK?
Yes. The request shape matches the OpenAI speech endpoint. Configure your SDK’s base_url to https://api.mtown.info/v1 and use your CalmVoice key. This allows direct integration using standard OpenAI client libraries without custom code.
What is the maximum input length?
The maximum input length is 4096 characters per request. For longer texts, split the text into parts of up to 4096 characters and join the resulting audio files. Spaces and punctuation count toward this limit.
How do I set the language explicitly?
Pass the optional language field with an ISO code. If omitted, the system guesses the language, defaulting to English for Latin script. Explicitly set it for non-English Latin-script text to ensure correct synthesis.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key (10 before the first top-up). Requests are processed sequentially. Exceeding the limit may cause requests to wait in a queue or fail, potentially delaying audio generation.
Is SSML supported in the input?
No, SSML is not supported. The API accepts plain text input only. You cannot use SSML tags for pronunciation or prosody control. Only the specified fields like voice, speed, and model are processed.
Can I stream the audio response?
No, streaming is not supported. The API returns the complete audio file in the response body. You must wait for the full synthesis to complete before receiving the audio data. There is no WebSocket or partial audio support.
What is the default voice if none is specified?
The voice field is required; you must explicitly provide one of the eight presets. You must explicitly provide one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion.
How do I handle long texts exceeding 4096 characters?
Split the text into chunks of up to 4096 characters. Send each chunk as a separate request. Then join the returned audio files to create the final output. This ensures compliance with the input length limit.
What is the difference between tts-1 and tts-1-hd?
Both models use the same engine and price. tts-1 and tts-1-hd are functionally identical in cost and processing. Choose either based on preference, as there is no price or engine difference between them.
How do I test the API with curl?
Use a POST request to https://api.mtown.info/v1/audio/speech. Include the Authorization: Bearer tts-... header. Send a JSON body with model, input, and voice. Check the response for the audio file or error details.
Are there any limits on concurrent requests?
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.
Can I request a specific audio format?
Yes. Specify the response_format field in the request body. Supported formats are mp3, wav, opus, flac, and pcm. This allows you to choose the format that best fits your application’s requirements.
First request
curl
curl https://api.mtown.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.mtown.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.mtown.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
CalmVoice uses standard Bearer token authentication for all API requests. Include your unique key in the Authorization header as Bearer tts-<your_key>. This token authorizes your account against the API base URL.
Bearer Token Usage
Pass the key via the Authorization: Bearer header in every request. The key grants access to your specific account balance and usage limits.
Key Issuance Process
Keys are issued upon account creation via Google sign-in or email registration. Each account holds one active key at a time, displayed on the /get-api-key/ dashboard.
Key Rotation
Issue a new key via your dashboard to invalidate the old one immediately. This ensures secure access management without downtime for your elderly care or assistive device applications.
Endpoint Overview
CalmVoice exposes three primary endpoints to facilitate integration with assistive device software. The speech generation endpoint processes text inputs and returns synthesized audio files, while the voices and models endpoints provide metadata for configuration.
Speech Generation Endpoint
Send a POST request to /v1/audio/speech with a JSON body containing the text, voice selection, and format preferences. The API returns the audio file directly in the response, enabling immediate playback or storage in your application.
- Endpoint: POST /v1/audio/speech
- Supports text up to 4096 characters
- Returns audio in selected format
Voices Listing Endpoint
Use GET /v1/voices to retrieve available voice presets, supported languages, and audio formats. This allows your application to dynamically present options to users without hardcoding voice identifiers or format constraints.
- Endpoint: GET /v1/voices
- Lists 8 voice presets
- Returns supported language codes
Models Endpoint
The GET /v1/models endpoint returns the available model identifiers. Currently, both tts-1 and tts-1-hd utilize the same engine, allowing for consistent behavior across different quality settings without requiring separate infrastructure.
- Endpoint: GET /v1/models
- Returns model identifiers
- No separate infrastructure required
Request Parameters
Configure the synthesis request by defining the input text, target voice, and playback parameters. The API accepts plain text up to 4,096 characters per request, where spaces and punctuation count toward the limit. For texts exceeding this length, split the input into chunks and join the resulting audio files to maintain continuity.
Input Text Field
The input field accepts a maximum of 4,096 characters. Each character, including spaces and punctuation, is billed. Requests are processed sequentially, so longer texts may experience queue delays.
Voice Selection
Select from eight presets optimized for clarity and consistency in assistive applications. Voices include aria, nova, luna, and sage for female tones, and felix, milo, atlas, and orion for male tones. All voices support all 23 languages.
- aria: warm, clear narrator
- nova: bright, upbeat
- luna: soft, storytelling
- sage: calm, instructional
- felix: energetic, promo
- milo: friendly, conversational
- atlas: neutral, news
- orion: deep, documentary
Speed and Language
Adjust playback speed between 0.25 and 4.0 using the speed parameter. The language field accepts an optional ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly set this field for non-English Latin-script inputs to ensure accuracy.
Response Formats
Select the output format to match your application’s audio processing pipeline. MP3 offers efficient compression for storage and streaming, while WAV provides uncompressed lossless quality for high-fidelity playback systems.
PCM returns raw uncompressed audio samples, ideal for direct hardware integration or custom encoding. All formats include an inaudible watermark identifying the synthetic origin.
MP3 Output
The API does not specify a default format; the client must explicitly select one of the supported formats (mp3, wav, opus, flac, pcm). It is suitable for most web and mobile applications where bandwidth efficiency matters.
WAV Output
WAV provides uncompressed audio, ensuring maximum fidelity for assistive devices requiring precise sound reproduction. This format is larger but avoids decoding artifacts.
PCM Raw Audio
PCM returns raw uncompressed audio samples. Use this when your hardware or software expects linear pulse-code modulation without container overhead.
OpenAI SDK Integration
Leverage the official OpenAI SDKs to integrate CalmVoice’s TTS API with minimal code changes. By adjusting the base URL, your existing infrastructure can route requests to our speech endpoint without requiring custom HTTP clients or proprietary wrappers.
This approach ensures compatibility with standard libraries used in backend services for elderly care and assistive device applications, allowing developers to maintain existing architectures while accessing our synthetic audio outputs.
Base URL Configuration
Configure the SDK client to point to https://api.mtown.info/v1. This single change redirects all standard speech generation calls to our infrastructure, enabling immediate use of our models without modifying the core request structure.
Client Initialization
Initialize the OpenAI client using your unique API key (tts-...). The client handles authentication headers automatically, ensuring secure transmission of text inputs to the synthesis engine. Ensure the key is valid and active for immediate access.
- Use standard OpenAI SDK languages (Python, Node.js, etc.)
Request Execution
Invoke the audio/speech endpoint with your text payload. The SDK manages the JSON body, including model selection (tts-1 or tts-1-hd), voice preset, and response format. The response returns the generated audio file directly.

Error Handling
Proper error handling ensures your elderly care application maintains audio continuity during API failures. The service returns standard HTTP codes to indicate success or failure, allowing your system to retry or log issues appropriately.
HTTP Status Codes
Use 200 for successful audio generation. Use 400 for bad requests, 401 for invalid API keys, and 429 for rate limit exceeded. Use 500 for server errors during synthesis.
Rate Limit Errors
New accounts receive 10 requests per minute. Once topped up, the limit increases to 60 requests per minute. Exceeding this returns a 429 status code.
Invalid Request Data
The API validates input text length (max 4096 characters) and voice names. Invalid parameters return a 400 error with a descriptive message. Failed requests are free: if synthesis fails, the charge is returned in full.
Curl Example
The API accepts standard JSON payloads via POST requests. Use the provided curl commands to verify connectivity and generate audio files directly from the command line.
Replace YOUR_API_KEY with your actual bearer token. The endpoint base URL is https://api.mtown.info/v1.
Basic Request
This example generates a short audio clip using the default "aria" voice in MP3 format. The text is limited to 4096 characters.
- curl -X POST https://api.mtown.info/v1/audio/speech \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1", "input": "Hello world.", "voice": "aria", "response_format": "mp3"}'
Custom Voice Parameter
Select from eight presets such as "milo" for conversational tones or "atlas" for neutral delivery. The voice field accepts any valid voice ID.
- curl -X POST https://api.mtown.info/v1/audio/speech \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -d '{"model": "tts-1", "input": "Patient check-in ready.", "voice": "atlas", "response_format": "wav"}'
Speed Adjustment
Adjust playback speed between 0.25 and 4.0. This is useful for synchronizing audio with assistive device interfaces or elderly user preferences.
- curl -X POST https://api.mtown.info/v1/audio/speech \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -d '{"model": "tts-1", "input": "Slow down.", "voice": "luna", "speed": 0.5, "response_format": "mp3"}'
Rate Limits
Rate limits define the throughput capacity of your integration. Understanding these constraints ensures consistent audio delivery for assistive devices without unexpected throttling during peak usage periods.
Standard Limit
Each API key is limited to 60 requests per minute (10 per minute before the first top-up). This limit applies per key, allowing you to scale by issuing additional keys if necessary.
- Limit is 60 requests/minute post-top-up.
- Limit is 10 requests/minute pre-top-up.
- Limits are enforced per API key.
Pre-Trial Limit
Accounts without a completed top-up operate at the reduced rate of 10 requests per minute. This ensures fair usage during the trial phase while maintaining service reliability.
Concurrency Behavior
Requests are processed sequentially. Under heavy load, additional requests may queue behind earlier ones, potentially increasing latency for long-form audio synthesis.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. You pay per character processed, not per voice type, ensuring predictable expenses as your user base grows.
23 languages
Any voice speaks any of these languages.
