Frequently asked questions
What is the base URL for the API?
The base URL is https://api.playabc999.com/v1. You can use the official OpenAI SDKs by changing the base_url to this address and providing your site-specific API key. This allows you to send POST requests to /v1/audio/speech with the same JSON body structure as the OpenAI speech endpoint.
Does the API support SSML tags?
No, the API does not support SSML. It accepts plain text input for synthesis. If you need specific pacing or pronunciation, you must manage that logic in your application code before sending the text to the endpoint, as the API processes the input string directly without parsing SSML markup.
Can I stream audio in real-time?
No, the API does not support streaming or WebSocket connections. You send a POST request with your text, and the API returns the complete audio file once synthesis is finished. You must wait for the full response to receive the audio data, which is suitable for batch processing workflows.
What is the maximum text length per request?
The maximum input text length is 4096 characters per request. If your medical guide or script exceeds this limit, you should split the text into smaller parts of up to 4096 characters, generate audio for each part, and then join the resulting audio files together in your application.
How do I specify the language for Latin script text?
If the language parameter is not set, the API guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, you must explicitly set the language parameter to the correct ISO code to ensure accurate synthesis, as the default guess may be incorrect.
Is there a Python SDK provided by the vendor?
No, we do not provide an official SDK. You can use the official OpenAI Python SDK by configuring the base_url to https://api.playabc999.com/v1. Alternatively, you can use any standard HTTP library to send POST requests with the required JSON body and Bearer authentication header.
What happens if I exceed the rate limit?
The rate limit is 60 requests per minute per key. If you exceed this, requests may be queued or rejected. New accounts start with a lower limit of 10 requests per minute until the first top-up. Ensure your application handles retries appropriately to manage these limits during high-volume synthesis tasks.
Can I change my API key if it is compromised?
Yes, you can issue a new API key at any time from your account dashboard. When you generate a new key, the old one stops working immediately. This ensures that if your key is compromised, you can revoke access instantly by issuing a replacement key without waiting for a delay.
Do the voices support emotional intonation?
No, the voices do not support emotion tags or custom emotional intonation. The eight presets have distinct styles, such as warm, bright, or calm, but these are fixed characteristics. You cannot dynamically adjust emotions within a single request; you must select the voice that best matches the desired tone.
Is the audio format PCM suitable for medical archives?
Yes, PCM is one of the supported response formats alongside MP3, WAV, OPUS, and FLAC. PCM provides uncompressed audio data, which is often preferred for archival purposes where file size is less critical than preserving the exact audio quality.
How do I handle the 4096 character limit for long patient guides?
Split your long text into chunks of up to 4096 characters. Send each chunk as a separate POST request to the speech endpoint. Once you receive the audio file for each part, join them sequentially in your application to create the complete audio file for the entire patient guide.
Are the audio files watermarked?
Yes, every generated audio file carries an inaudible watermark that marks it as synthetic speech. This watermark is embedded within the audio data itself and is not visible or audible to the listener, serving as a marker to identify the content as AI-generated voice synthesis from our API.
Can I use the same key for multiple applications?
Yes, you can use the same API key across multiple applications or services. The rate limit of 60 requests per minute applies per key, so all applications sharing that key will collectively count against the same limit. Monitor your usage to ensure you do not exceed the per-key threshold.
What is the difference between tts-1 and tts-1-hd?
Both tts-1 and tts-1-hd use the same engine and have the same price of $10 per 1 million characters. The primary difference is the audio quality, with tts-1-hd offering higher fidelity. Functionally, they are identical in terms of supported voices, languages, and request parameters.
First request
curl
curl https://api.playabc999.com/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.playabc999.com/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.playabc999.com/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 and Keys
MediVoice provides a reliable speech synthesis API for healthcare teams. Access is controlled via a single active API key per account, ensuring straightforward security for clinical and administrative integrations.
Generating Your API Key
Sign up on /get-api-key/ using Google or email. Your key is displayed immediately alongside your balance and usage stats.
Bearer Token Format
Include the key in the Authorization header as: Authorization: Bearer tts-.... Use this format for all API requests.
Key Rotation Policy
Issue a new key at any time from the dashboard. The previous key stops working immediately, ensuring seamless transitions during security updates.
Endpoint Overview
The core of the MediVoice API is the speech generation endpoint. You send a POST request to /v1/audio/speech with your text and receive an audio file. This endpoint handles all synthesis tasks for healthcare scripts and patient guides.
For reference, you can list available voices and models via GET /v1/voices and GET /v1/models. These endpoints provide the necessary metadata for integration without requiring audio generation.
Speech Generation Endpoint
Send a POST request to https://api.playabc999.com/v1/audio/speech. This endpoint accepts JSON and returns the synthesized audio file directly in the response body.
Voices and Models List
Retrieve the full list of available voices, languages, and formats using GET /v1/voices. Use GET /v1/models to confirm the available models, such as tts-1 and tts-1-hd, which share the same engine and price.
- tts-1: Standard model
- tts-1-hd: High-definition model
Request Body Structure
The request body is a JSON object containing the text to be spoken, the selected voice, and optional parameters like speed and language. The input text must not exceed 4096 characters per request.
Include the required fields: model, input, voice, and response_format. Optional fields include speed and language.
- model: "tts-1" or "tts-1-hd"
- input: text (max 4096 chars)
- voice: one of 8 presets
- response_format: mp3, wav, opus, flac, or pcm
- speed: 0.25–4.0
- language: optional ISO code
Quickstart with cURL
Use cURL to send medical text directly to the TTS endpoint. This method works for any programming environment and helps verify your API key before building complex integrations.
The example below generates a short patient guide excerpt using the "aria" voice. Replace the placeholder key with your actual token from the dashboard.
Basic Request Example
Send a POST request to the speech endpoint. The body must include the model, input text, voice preset, and desired audio format.
- Use
tts-1for standard cost ortts-1-hdfor higher quality. - Specify
ariafor a warm, clear narrator tone suitable for patient instructions. - Set
response_formattomp3for broad compatibility.
Headers and Body
Include your API key in the Authorization header. The input text must not exceed 4096 characters. Spaces and punctuation count toward this limit.
- Header:
Authorization: Bearer tts-... - Body: JSON object with
model,input,voice, andresponse_format. - Optional:
speed(0.25–4.0) andlanguage(ISO code).
Response Handling
A successful response returns the audio file directly in the body. Check the HTTP status code to confirm success or identify errors.
- Status 200: Audio data returned.
- Status 401: Invalid or expired API key.
- Status 429: Rate limit exceeded.
Integration with OpenAI SDK
To adapt the OpenAI SDK for MediVoice, update the base URL to https://api.playabc999.com/v1. This allows you to use standard OpenAI client libraries without custom wrappers.
Initialize the client with your tts-... bearer token. The API accepts the same JSON structure as OpenAI’s speech endpoint, ensuring seamless integration for existing developers.
Base URL Configuration
Set the SDK’s base URL to https://api.playabc999.com/v1. This redirects requests to our TTS engine while maintaining compatibility with OpenAI’s request schema.
Client Initialization
Create a new client instance passing your API key. The key format is tts-... and must be included in the Authorization header.
- Use
base_urlparameter in your SDK client constructor.
Method Usage
Call the audio.speech method with your model (tts-1 or tts-1-hd), voice, input text, and desired response format. The SDK handles the request and returns the audio file directly.
Audio Formats and Options
MediVoice supports multiple audio formats to suit different playback environments. You can request files in MP3, WAV, Opus, FLAC, or PCM via the response_format field. These formats ensure compatibility with electronic health record systems and patient education platforms.
Supported Formats (MP3, WAV, etc.)
Choose MP3 for compact file sizes or WAV/FLAC for lossless audio. PCM is available for raw audio processing. All generated files include an inaudible synthetic watermark.
Speed Adjustment Range
Adjust speech pace between 0.25x and 4.0x using the speed parameter. Slower speeds aid comprehension for complex medical terminology, while faster speeds help teams review longer patient guides efficiently.
Language Code Specification
Specify the language parameter with an ISO code (e.g., en, de, es) to guide synthesis. Without it, Latin text defaults to English. Our API supports 23 languages, including Arabic, Chinese, French, German, Hindi, Japanese, Korean, and Spanish. Non-supported languages like Vietnamese or Thai will not render correctly.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
- Not supported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali

Rate Limits and Quotas
MediVoice enforces a rate limit of 60 requests per minute per API key to ensure stable performance for healthcare teams generating patient guides and medical scripts.
Requests Per Minute
You can process up to 60 synthesis requests each minute. Since requests are processed sequentially, high-volume generation may experience slight queuing delays during peak usage, which is typical for our infrastructure.
Initial Limit for New Keys
New API keys start with a reduced limit of 10 requests per minute. This applies until you perform your first top-up, after which the full 60 requests per minute quota becomes available immediately.
Limit Increase Process
There are no manual requests for higher limits or tiered plans. Your limit increases automatically and instantly once you add funds via USDT (TRC-20). No minimum spend is required to unlock the full rate; the minimum top-up is $5.
Handling Long Texts
Medical documents often exceed the single-request limit. Our API processes up to 4096 characters per call, requiring you to split longer texts into manageable segments before submission.
Accurate segmentation ensures consistent audio output. By joining the resulting audio files, you create a seamless listening experience for patient guides or educational scripts without gaps or format changes.
4096 Character Limit
Each API request accepts a maximum of 4096 characters, including spaces and punctuation. This constraint applies to all models and voices, ensuring predictable processing times for standard-length medical texts.
Splitting and Joining Audio
Split your input text into chunks of 4096 characters or less. Submit each chunk via separate POST requests to the speech endpoint.
After receiving all audio files, concatenate them in the order of the original text. Supported formats like WAV and MP3 allow straightforward merging using standard audio libraries, though format compatibility should be verified.
- Preserve character count accuracy when splitting to avoid truncation.
- Maintain original order to ensure logical audio flow.
Queue Processing Behavior
Requests are processed sequentially. Under load, a request may wait in a queue before synthesis begins.
Long texts require multiple requests, so total generation time increases proportionally. Typical speed is roughly real-time, but queue delays may extend total processing duration for large documents.
Error Codes and Responses
MediVoice returns standard HTTP status codes to indicate request success or failure. Understanding these codes helps you implement robust error handling in your clinical workflows.
Common HTTP Errors
Use 401 for invalid or expired API keys, 429 for exceeding the 60 requests per minute limit, and 500 for server-side issues. These ensure your application can retry or notify admins appropriately.
Audio Generation Errors
Errors such as invalid voice IDs or unsupported language codes return specific details. Failed synthesis is free, so no charge is applied if the audio file is not generated successfully.
Debugging Tips
Check the error object in the JSON response for a clear message. Ensure your text input is under 4096 characters and that the language field matches the text script to avoid guessing errors.
- Verify
Authorization: Bearer tts-...format - Check character count before sending
- Confirm ISO language codes
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Note any specific words or phrases that were difficult to catch.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- Python documentation
- LibriVox public-domain audiobooks
- MDN: Web Speech API
- openai-node on GitHub
- TRON developer hub: TRC-20
- Creative Commons Attribution 4.0
- LibriTTS-R corpus (OpenSLR 141)
- OpenAI API reference: create speech
- FFmpeg documentation
- W3C WAI: making audio and video accessible
- ISO 639 language codes
