Frequently asked questions
How do I get an API key?
Navigate to /get-api-key/ and sign in using Google or create an account with email and password. The dashboard displays your active Bearer key, balance, and usage statistics. You can issue a new key at any time, which immediately invalidates the previous one.
What is the base URL for the API?
The API base URL is https://api.playyy6.com/v1. All requests, including speech synthesis and voice listing, use this domain. Ensure your client library points to this endpoint to correctly route your text-to-speech requests.
Can I use the OpenAI SDK with this API?
Yes. The request shape matches the OpenAI speech endpoint. Simply configure your OpenAI SDK’s base_url to https://api.playyy6.com/v1 and use your site-specific API key. This allows you to use official OpenAI SDKs without modification.
What is the maximum text length?
Each request supports up to 4096 characters of input text. If your content exceeds this limit, you must split the text into smaller parts and join the resulting audio files. Spaces and punctuation count toward this character limit.
Which format is best for patient apps?
MP3 is widely supported by most mobile and web players. You can also choose WAV, OPUS, FLAC, or PCM depending on your specific quality or bandwidth requirements. All formats are returned directly in the API response.
How do I set the language to Hindi?
Include the optional 'language' field set to 'hi' in your JSON request body. While the API guesses language from the script, explicitly setting it ensures accurate Hindi synthesis. Hindi is one of the 23 supported languages.
What happens if the server is busy?
Requests are processed sequentially. Under load, your request may wait in a queue. Typical speed is roughly real-time, but short phrases may take a few seconds. Failed requests are free, but busy servers may increase latency.
Do I need to split long texts manually?
Yes. Since the maximum input is 4096 characters, you must split longer texts into parts yourself. After receiving the audio files for each part, your application should join them to create the final audio file.
Is the API compatible with React Native?
Yes. Since the API uses standard HTTP POST requests with JSON bodies, it works with any HTTP client.
How do I handle rate limit errors?
The limit is 60 requests per minute per key. If you exceed this, implement exponential backoff in your client. New accounts start with a 10 requests per minute limit until the first top-up is processed.
Can I use SSML tags?
No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You must rely on the natural intonation of the eight available voices.
Is there a webhook for completion?
No. The API is synchronous; it returns the audio file directly in the response.
How do I test the API with a sample?
Use the ready curl example provided on the /get-api-key/ dashboard page. It demonstrates the correct JSON body structure, including model, voice, and input fields. This allows you to verify connectivity and authentication immediately.
What is the default voice?
The API does not specify a single default voice in the documentation, but you must provide a 'voice' parameter. Common choices include 'aria' for warm narration or 'sage' for instructional content. You must explicitly select one of the eight presets.
First request
curl
curl https://api.playyy6.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.playyy6.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.playyy6.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
To begin integration, sign up at /get-api-key/ using Google or email. The dashboard displays your active API key and current balance. This key authenticates all requests to the API base https://api.playyy6.com/v1.
Generating Your API Key
Access the /get-api-key/ page to create an account. Google sign-in includes a $0.50 trial credit valid for 7 days; email accounts start without credit. The dashboard shows your key, balance, and usage stats immediately.
- Google sign-up includes $0.50 trial credit
- Email accounts start without trial credit
- Key displayed on dashboard immediately
Bearer Token Format
Include the header Authorization: Bearer tts-... in every request. The token must match the key generated in your account. One active key exists per account; use this exact string for authentication.
Key Rotation Policy
Issue a new key via the dashboard at any time. The previous key stops working immediately upon issuance. This ensures secure access control without downtime if you rotate credentials frequently.
Endpoint: /v1/audio/speech
The core synthesis endpoint accepts text and returns audio. It mirrors the OpenAI speech structure, allowing healthcare startups to leverage existing integrations by simply updating the base URL to https://api.playyy6.com/v1. Send a POST request with your API key in the Authorization header to generate clinical audio files instantly.
This endpoint handles the conversion of up to 4096 characters of patient guide text into speech. It supports multiple audio formats and speed adjustments, ensuring the output fits seamlessly into your existing digital health workflows without requiring custom parsing logic.
POST Method Structure
Send a POST request to /v1/audio/speech. Include your API key as a Bearer token in the Authorization header. The request body must be valid JSON containing the model, input text, voice selection, and optional parameters like speed and language code.
JSON Body Parameters
The body requires a model (tts-1 or tts-1-hd), input string (max 4096 chars), and voice preset. Optional fields include response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0), and language (ISO code). If language is omitted, the system guesses it from the script, defaulting to English for Latin text.
Ensure you set the language field explicitly for non-English content, such as Hindi or German, to avoid misidentification. The system processes requests sequentially, so long texts may queue if the API is under load.
Response Format
On success, the response contains the audio file in the requested format. Failed requests return a standard error JSON object without charge. The API does not store the generated audio; you receive it directly in the response.
Required and Optional Fields
The API accepts plain text input up to 4096 characters per request. Spaces and punctuation count toward this limit, so patient guides may require splitting longer instructions into separate calls.
You can adjust generation speed between 0.25x and 4.0x using the speed parameter. This allows clinicians to slow down complex medical terminology or accelerate standard discharge instructions for efficiency.
Input Text Limit
Each request handles a maximum of 4096 characters. For longer patient guides, split the text into parts, generate audio for each, and join the resulting files sequentially.
Voice Selection
Choose from eight presets like sage for calm instructional tones or nova for upbeat updates. All voices support the full range of 23 languages, ensuring consistent quality across multilingual content.
- Select
modelastts-1ortts-1-hdfor identical audio quality at the same price.
Language Code Specification
Set the language field with an ISO code (e.g., hi for Hindi, en for English). Without this, the system guesses the language from the script, defaulting to English for Latin text.
Explicitly defining the language prevents mispronunciation in mixed-script documents, ensuring accurate delivery for diverse patient demographics.
- Supported languages include Hindi, Spanish, German, and 20 others.
Supported Audio Formats
The API supports MP3, WAV, FLAC, and OPUS formats, allowing you to choose the optimal file type for your healthcare application’s infrastructure. Each format balances file size, quality, and playback compatibility differently depending on your delivery method.
MP3 for Web Playback
MP3 is the default and most efficient choice for web-based patient guides. It offers high compression with minimal quality loss, ensuring fast loading times for mobile apps and web portals where bandwidth may be limited.
WAV for High Quality
WAV provides uncompressed audio, preserving the full fidelity of the synthetic voice. This format is ideal for archival purposes or when your clinical review process requires lossless audio to ensure no detail is lost in transmission.
- Lossless quality for precise clinical review
- Larger file sizes compared to compressed formats
FLAC and OPUS Options
FLAC offers lossless compression, reducing file size without sacrificing audio integrity, while OPUS provides excellent quality at low bitrates. These options are useful for storing large volumes of multilingual medical content efficiently.
- FLAC: Lossless compression for storage efficiency
- OPUS: Low bitrate, high efficiency
Rate Limits and Quotas
The API enforces a strict limit of 60 requests per minute per active key. This cap applies to all synthesis endpoints and ensures stable performance for batch processing patient guides. If you exceed this threshold, subsequent requests will receive a 429 Too Many Requests error until the window resets.
Requests Per Minute
Standard accounts can process up to 60 requests per minute. This limit is per key, so rotating keys allows you to scale throughput. For healthcare startups generating multilingual medical content, this rate supports steady batch uploads without overwhelming the server.
- Limit: 60 requests/minute/key
- Applies to all synthesis calls
Pre-Top-Up Limit
New accounts without a top-up are restricted to 10 requests per minute. This lower limit allows testing the integration with sample patient instructions before committing to USDT payments. Once you top up, the limit increases to the full 60 requests per minute.
Queue Behavior
Requests are processed sequentially. Under high load, a request may wait in a queue before synthesis begins. Longer texts take more time, so plan your batching strategy accordingly. Failed requests do not consume your character quota but may still count against the rate limit.

Error Handling
Error handling ensures your healthcare application gracefully manages synthesis failures without disrupting patient workflows. The API returns standard HTTP status codes to indicate success or specific failure modes, allowing your backend to retry or alert users appropriately.
Common HTTP Errors
Use 401 for invalid or expired API keys, 429 for rate limit exceeded (60 req/min), and 500 for server-side synthesis failures. Failed requests incur no charge, so you can safely retry with exponential backoff.
Invalid Voice ID
Passing an unsupported voice ID returns a 400 error. Only eight presets are available (e.g., aria, nova, atlas). Use GET /v1/voices to verify valid IDs before sending speech requests to ensure consistent audio output.
Text Too Long Error
Input text exceeding 4,096 characters triggers a 400 error. Split longer medical guides into segments under this limit. Concatenate the resulting audio files client-side to reconstruct the full patient guide without losing clarity.
Code Examples
The following examples demonstrate how to integrate MediVoice API into your healthcare application for generating patient guides. These snippets cover basic usage via command line, OpenAI SDK integration, and a standard Python script for batch processing multilingual medical content.
All examples assume you have replaced the placeholder key with your actual bearer token. The API follows the OpenAI speech endpoint structure, allowing you to use familiar libraries with a simple base URL adjustment.
Curl Command Example
Use this command to generate a quick audio file. It sends a request to the speech endpoint with Hindi text and the 'aria' voice, returning an MP3 file saved locally.
- Replace
YOUR_API_KEYwith your secret key. - Adjust the
inputfield with your patient instruction text. - The command saves the output as
output.mp3.
OpenAI SDK Integration
Import the OpenAI SDK and set the base URL to https://api.playyy6.com/v1. This allows you to use standard SDK methods to synthesize speech without custom HTTP handling.
- Set
base_urlto the MediVoice API endpoint. - Use the
Audiomodel class for speech generation. - Works with the official OpenAI SDKs.
Python Script Sample
This script handles text splitting for longer medical documents. It iterates through chunks, requests audio for each, and combines them into a single file for seamless patient playback.
- Split input text into 4096-character chunks.
- Send each chunk to the API sequentially.
- Concatenate the resulting audio files.
Voices Endpoint: /v1/voices
The GET /v1/voices endpoint returns a JSON array of all available voice presets, their associated languages, and supported output formats. This list allows your application to dynamically populate dropdown menus or selection interfaces without hardcoding voice IDs.
Listing Available Voices
Calling this endpoint provides metadata for eight distinct voices, including Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. Each entry includes the voice ID, gender, and a brief description of the vocal style, enabling precise selection for patient guides or medical instructions.
- Retrieves all 8 voice presets
- Includes gender and style metadata
- Returns supported format list per voice
Language Compatibility
Each voice supports all 23 languages, including Hindi, English, German, and Spanish. The API does not restrict language usage per voice, allowing you to use a single voice ID across multiple medical content tracks. If the language field is omitted, the system guesses the language from the input script.
- All voices support 23 languages
- No language-voice restrictions
- Auto-detection defaults to English for Latin script
Voice Characteristics
Voices are categorized by tone: female options include Aria (warm narrator) and Sage (calm instructor), while male options include Felix (energetic) and Atlas (neutral news). These presets are designed for clarity in clinical contexts, ensuring patient instructions are easily understood. All voices are based on licensed recordings from LibriVox.
- 4 female voices: Aria, Nova, Luna, Sage
- 4 male voices: Felix, Milo, Atlas, Orion
- Licensed from LibriTTS-R (CC BY 4.0)
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Email-based accounts start without trial credit, requiring immediate top-up to begin generation.
23 languages
Any voice speaks any of these languages.
