Frequently asked questions
What is the best voice for reading medical instructions?
Q: Which voice is best for reading medical instructions? A: Sage is designed for calm, instructional content, making it ideal for medical guidance. Alternatively, Atlas offers a neutral, news-style tone suitable for clear delivery of clinical information. You can choose between these eight presets based on your specific audience needs.
Can I use the API to read Bible verses for patient comfort?
Yes, you can generate audio from any text up to 4096 characters. Since the API supports 23 languages, you can easily convert Bible verses into audio files for patient comfort without needing special formatting or additional infrastructure.
How do I handle special characters in medical text?
Spaces and punctuation count as characters toward your 4096-character limit. The API processes standard text input directly, so special characters in medical notes are handled naturally. You do not need SSML tags for basic symbols.
Is the API fast enough for real-time patient interaction?
Synthesis takes roughly real time, generating about 25 characters per second. Short phrases may take a few seconds. Since requests are processed sequentially, high load might introduce queue delays, so it is not guaranteed for strict real-time interactions.
Do I need to pay for every voice used in a document?
Pricing is based on character count, not the number of voices used. You pay $0.01 per 1,000 characters regardless of whether you switch between Aria, Nova, or Atlas within your document. Each request is billed individually based on input length.
Can I generate audio in multiple languages from one text?
Each request processes a single text input. To generate audio in multiple languages, you must send separate requests for each language version of your text. The API supports 23 languages, but it does not translate or mix languages in one file.
What happens if the text contains medical abbreviations?
The API reads text as provided without custom pronunciation dictionaries or phoneme dictionaries. Abbreviations will be read based on standard letter pronunciation. You do not have access to phoneme dictionaries to customize how specific medical terms or acronyms are pronounced in the output audio.
Is the audio quality suitable for hearing impaired patients?
Audio is generated in formats like WAV, FLAC, or MP3. While quality is clear, the API does not guarantee specific audio profiles for hearing impairments. You can adjust speed between 0.25 and 4.0 to help listeners process the content at their preferred pace.
How do I ensure the audio matches the original text?
The API generates audio directly from the input text string. Since there is no SSML layer, the output strictly follows the words provided. Ensure your input text is accurate before sending the request, as the audio reflects it exactly.
Can I change the voice after the audio is generated?
No, each request generates a static audio file with a specific voice preset. You cannot retroactively change the voice of an existing file. To use a different voice, you must send a new API request with the desired voice parameter.
Is there a limit to how many files I can generate per day?
There is no daily limit on the number of files, only a rate limit of 60 requests per minute per key. You can generate as many files as needed, provided you stay within the per-minute request threshold and have sufficient balance.
Do I need to store the audio files myself?
Generated audio is returned in the response and not stored by the API. You must handle the storage of your audio files. Request metadata is kept for billing, but the actual audio content is delivered to your application for your own use.
Can I use the audio for educational training materials?
Yes, the API provides reliable speech synthesis suitable for educational scripts and patient guides. The generated audio files can be used in training materials. Each file carries an inaudible synthetic watermark.
How do I specify the language if the text is ambiguous?
If the language is not set, it is guessed from the script. For non-English Latin-script text, you should explicitly set the language parameter. This ensures accurate pronunciation, as the default guess for Latin script is English, which may misread other languages.
Understanding the Input Requirements
Generating audio from medical text requires strict adherence to input constraints to ensure successful synthesis. The API accepts plain text inputs with a hard limit of 4,096 characters per request. This constraint applies to the entire payload, including spaces and punctuation, which are counted as individual characters. Understanding these limits is essential for structuring patient guides efficiently.
Language detection is not always accurate because the system guesses the language from the script if not explicitly set. Latin script defaults to English, which can cause errors for non-English content. Explicitly defining the language parameter ensures the correct voice model processes the medical terminology accurately.
Text Length Constraints
Each API request supports a maximum of 4,096 characters. If your patient guide exceeds this limit, you must split the text into smaller chunks. The system processes requests sequentially, so longer documents may queue, but the character limit remains a strict boundary for a single synthesis job.
- Maximum input: 4,096 characters per request
- Includes all spaces and punctuation
- Exceeding limits causes request rejection
Character Counting Rules
Every character in your input string contributes to the count and the final bill. Spaces, commas, and special symbols are not free; they count toward the 4,096-character limit and the per-character pricing. This means concise phrasing in medical instructions can help optimize both processing time and costs.
Language Detection Logic
The API infers the language from the character set if the language field is omitted. For example, Latin characters default to English. If your medical guide is in Spanish, German, or French, you must set the language parameter to the correct ISO code. This prevents the engine from misinterpreting medical terms or accents.
Choosing the Right Voice for Medical Content
Selecting the appropriate voice ensures medical instructions are clear and patient guides remain engaging. Our API offers eight distinct presets, each based on licensed recordings.
Sage for Instructional Text
Sage provides a calm, instructional tone ideal for step-by-step procedures or medication guides. Its steady delivery helps patients follow complex directions without confusion, making it a reliable choice for administrative scripts.
- Best for: Procedural instructions
- Tone: Calm and instructional
Aria for Narrative Guides
Aria offers a warm, clear narrator voice suitable for storytelling-style patient education. It works well for background information or wellness tips where a softer, more engaging sound improves retention.
- Best for: Educational narratives
- Tone: Warm and clear
Atlas for News and Updates
Atlas delivers a neutral, news-style voice perfect for clinic announcements or policy updates. Its professional neutrality ensures that factual information is conveyed without emotional bias, suitable for broad administrative communications.
- Best for: Announcements
- Tone: Neutral and professional
Configuring the API Request
Configuring the API request requires precise alignment with MediVoice’s endpoint structure. You send a POST request to https://api.playabc999.com/v1/audio/speech using the standard JSON body shape compatible with OpenAI SDKs. This ensures your existing healthcare integrations can adapt with minimal code changes, simply by updating the base URL and injecting your Bearer token.
Setting the Model Parameter
Specify model as either tts-1 or tts-1-hd. Both options use the same underlying engine and price point, so your choice depends on whether you prioritize specific acoustic qualities over cost, though the pricing remains identical at $0.01 per 1,000 characters regardless of the model selected.
Defining the Voice Preset
Select one of the eight presets, such as sage for calm, instructional patient guides or atlas for neutral clinical updates. Ensure the language field matches the text script to avoid incorrect voice synthesis, as the system defaults to English for Latin-script text if unspecified.
Selecting the Audio Format
Choose from mp3, wav, opus, flac, or pcm via the response_format field. MP3 is recommended for most web-based patient portals due to its balance of quality and file size, while WAV may be preferred for internal clinical archives requiring lossless fidelity.
Handling the Response and Audio File
The API returns the synthesized audio as raw binary data in the HTTP response body. This direct delivery means your application receives the complete audio file immediately after successful synthesis, without needing to query a separate storage endpoint.
Receiving the Binary Data
Upon a successful POST request, the response contains the audio bytes directly. Ensure your client parses the response body as binary rather than JSON, as the content type matches your selected response_format (e.g., audio/mpeg for MP3).
Saving the Audio File
Write the received binary stream to your local storage or cloud bucket using the filename suggested by the Content-Disposition header, or generate a unique identifier for the patient guide segment. This ensures the audio file is permanently stored for distribution.
Verifying File Integrity
Check the response status code (200) to confirm delivery. You may validate the file header matches the requested format (e.g., verifying MP3 ID3 tags) to prevent corruption during transmission.
Processing Long Medical Documents
Medical patient guides often exceed the 4,096-character limit per request. To handle lengthy documents, you must split the text into smaller chunks that fit within this constraint before sending them to the API.
Splitting Text into Chunks
Divide your medical text into segments of up to 4,096 characters.
- Maximum 4,096 characters per request
- Count spaces and punctuation as characters
- Split at natural language breaks
Generating Audio for Each Chunk
Send each chunk as a separate POST request to the speech endpoint. The API processes requests sequentially, so longer texts may experience queue delays. Each request returns a distinct audio file.
Concatenating Audio Files
Once all chunks are synthesized, combine the resulting audio files in the correct order. This creates a single, continuous patient guide audio file for your users.
Error Handling and Retries
When synthesizing medical guides, failures can occur due to temporary server load or invalid inputs. Knowing how to distinguish a temporary glitch from a billing issue ensures your team’s workflow remains uninterrupted and audio files are delivered reliably.
Identifying Synthesis Failures
The API returns specific error codes when a request fails, such as invalid parameters or server overload. Unlike successful requests, failed syntheses incur no charge, so your balance remains intact even if the audio file is not generated.
- Check HTTP status codes in the API response
- Review error messages for specific failure reasons
- Verify input text does not exceed 4096 characters
Retrying Failed Requests
Implement automatic retries for transient errors like rate limits or server timeouts. Since failed requests are free, you can retry without worrying about duplicate charges, ensuring that critical patient instructions are eventually generated.
- Use exponential backoff for retry logic
- Retry on 429 (Rate Limit) or 5xx errors
- Avoid retrying on 4xx client errors (e.g., invalid voice ID)
Checking Balance Status
Before generating large batches of medical content, verify your account balance and trial status. This prevents unexpected interruptions during patient guide generation, especially when using the free trial credit or USDT top-ups.
- Check balance via the /get-api-key/ dashboard
- Monitor character usage to avoid running out of credit
- Ensure TRC-20 transfers are credited before bulk generation
Optimizing for Large Teams
MediVoice supports large clinical teams by allowing easy key rotation. If a key is compromised, issue a new one via the dashboard; the old key stops immediately, ensuring secure access without downtime.
Teams can manage multiple keys for different departments or projects.
Managing API Keys
Each account holds one active key at a time. You can generate a new key instantly from the dashboard, and the previous key becomes invalid immediately. This ensures that if a key is exposed, access is revoked without waiting for a cycle.
- Issue new keys instantly via the dashboard
- Old keys stop working immediately
- One active key per account
Monitoring Rate Limits
The API allows 60 requests per minute per key. New accounts start with 10 requests per minute until the first top-up. Teams should monitor their usage to avoid queuing delays, especially when generating large batches of patient guides.
- 60 requests per minute per key
- 10 requests per minute for new accounts
- Requests process sequentially, potentially queuing under load
Auditing Usage Statistics
Track characters consumed and billing status directly in the account dashboard. The system keeps request metadata for billing purposes, allowing teams to verify costs and ensure accurate budgeting for large-scale audio production.
- View character usage in the dashboard
- Check balance and trial status
- Metadata retained for billing accuracy

Security and Data Privacy
MediVoice ensures that your patient guide content remains private and secure. When you send text to our API, the input is used solely for the immediate synthesis of the audio file. We do not use your medical texts or scripts to train our models, ensuring your proprietary clinical content stays yours.
Once the audio is generated and returned in the response, the input text is not stored for long-term use. This approach minimizes data retention risks while maintaining the integrity of your patient education materials.
Input Data Usage
Your text is processed strictly for synthesis. No training data usage means your specific medical terminology and patient instructions remain confidential and are not absorbed into our general model improvements.
Metadata Retention
We retain request metadata—such as timestamp, character count, and status—exclusively for billing and usage auditing purposes. This data helps us accurately track your character consumption against your API key balance.
Synthetic Watermarking
Every audio file generated through our API includes an inaudible digital watermark. This marks the file as synthetic speech, providing a clear distinction between AI-generated patient guides and human-recorded audio without affecting playback quality.
This watermark helps identify the source of the audio as MediVoice-generated, ensuring transparency in your content delivery workflows.
- Inaudible to listeners
- Marked as synthetic
- No impact on audio quality
Testing Your Integration
Testing ensures your integration handles medical text correctly. Start by claiming the $0.50 free trial credit upon Google sign-in. This provides approximately 50,000 characters to verify functionality without immediate payment commitment.
Use the trial to run basic requests and confirm that your client code correctly processes responses. This step validates your setup before committing to larger volumes or USDT top-ups.
Using the Free Trial
Sign in via Google to receive $0.50 in credit, valid for seven days. This allowance covers roughly 50,000 characters, sufficient for testing various voice presets and formats.
Email-based accounts do not receive this initial credit, so consider Google sign-in for immediate testing capability.
- Claim $0.50 credit automatically upon Google sign-in.
- Credit expires after seven days if unused.
- Covers approx. 50,000 characters of text.
Running Sample Requests
Send a POST request to https://api.playabc999.com/v1/audio/speech using the provided key. Use a short medical text, such as a dosage instruction, to verify response speed and format.
Check that the response returns binary audio data. Failed requests incur no charge, allowing safe experimentation with different models like tts-1 or tts-1-hd.
- Use
tts-1ortts-1-hdmodels. - Verify binary audio response structure.
- No charge for failed synthesis requests.
Validating Audio Output
Ensure the generated audio is clear and matches the expected language. For non-English Latin text, explicitly set the language parameter to avoid incorrect English default detection.
Verify that the audio file includes the synthetic watermark, confirming it is generated speech. Check that the file format (mp3, wav, etc.) matches your request settings.
- Set
languageparameter for non-English text. - Verify synthetic watermark presence.
- Confirm requested audio format (mp3, wav, opus, flac, pcm).
Support and Documentation
Comprehensive documentation is available at /docs/ to help your team integrate the TTS API efficiently. The guides cover endpoint details, parameter descriptions, and ready-to-use code examples for common medical text workflows.
For direct assistance, our support team is available via email only. We do not offer phone lines or live chat, ensuring focused responses for technical inquiries from healthcare teams.
Accessing Full Docs
Visit /docs/ for complete technical references. The documentation explains all request fields, including model selection and audio formats, with practical examples for generating patient guides.
You can also test endpoints directly using the curl examples provided in the documentation to verify your configuration before full implementation.
- API endpoint reference
- Code examples in multiple languages
- Parameter definitions
Contacting Support via Email
Send your questions to our support email address. Our team reviews inquiries and provides detailed answers to help resolve integration issues or clarify billing details.
Since we do not offer phone support, email remains the primary channel for all user communications.
Reporting Issues
If you encounter synthesis failures or unusual behavior, describe the issue with your request ID and parameters. Our team investigates these reports to improve service reliability.
Include relevant logs or error messages to help us diagnose the problem quickly and restore your workflow.
Note that while we monitor service status, we do not provide an official SLA or uptime guarantee.
- Request ID reference
- Error log details
Common Pitfalls in Medical TTS
Medical TTS systems often misinterpret language if the language parameter is omitted. Since Latin-script text defaults to English, a German patient guide might be read with an English accent, reducing clarity for non-native speakers.
Ignoring character limits leads to truncated audio. Each request supports only 4096 characters. Exceeding this limit causes silent failures or incomplete sentences, disrupting the patient guide's flow.
Rate limits can halt production. The API allows 60 requests per minute. Large teams processing many guides simultaneously may hit this cap, requiring queuing logic to avoid delays.
Incorrect Language Codes
Assuming the system guesses correctly can ruin comprehension. If your patient guide is in Spanish but you send Latin text without setting language: es, the engine defaults to English. This creates an unnatural listening experience for users expecting native pronunciation.
Always explicitly define the language field for any language other than English, even if the script is Latin. This ensures the synthesizer applies the correct phonetic rules for languages like French, German, or Dutch.
- Set
languageexplicitly for all non-English texts. - Do not rely on automatic detection for Latin scripts.
- Verify output audio for accent consistency.
Ignoring Character Limits
The API enforces a strict 4096-character limit per request. Sending a long medical leaflet in one call will either fail or truncate the audio. You must split your text into chunks of this size before sending.
Use a script to split your document at sentence boundaries to avoid cutting words in half. This ensures each audio segment is complete and coherent when concatenated.
- Max 4096 characters per request.
- Split text at sentence boundaries.
- Concatenate segments after generation.
Misunderstanding Rate Limits
New accounts start with 10 requests per minute. Large clinical teams processing many guides may exhaust this quickly. If you exceed the 60 requests per minute limit, requests will queue or fail.
Monitor your usage via the dashboard. If you experience delays, consider batching requests or upgrading your key status. Failed requests are free, so retrying after a brief pause is safe.
- Start with 10 requests/minute.
- Max 60 requests/minute after top-up.
- Queue requests to avoid limits.
Next Steps for Implementation
Integrate the TTS API into your patient portal by passing structured medical text to the POST /v1/audio/speech endpoint. Use the tts-1 model with the sage voice for clear, instructional tone. Cache the resulting audio files to reduce API calls and improve load times for users.
For email guides, generate MP3 files via your backend and attach them directly or link to hosted audio. Ensure each guide includes a fallback text version. This approach keeps email clients compatible while providing accessible audio for visually impaired patients.
Integrating into Patient Portal
Embed the API call within your portal’s backend to convert static medical text into dynamic audio. Use the sage voice preset for instructional clarity. Cache responses to minimize latency and API costs for frequently accessed guides.
Ensure your portal handles the 4096-character limit by splitting longer documents. Concatenate the resulting audio chunks seamlessly for a continuous listening experience.
- Use
tts-1model for cost efficiency - Cache audio to reduce API calls
- Implement chunking for long documents
Adding Audio to Email Guides
Generate MP3 files via your backend and attach them directly or link to hosted audio. Ensure each guide includes a fallback text version. This approach keeps email clients compatible while providing accessible audio for visually impaired patients.
Leverage the aria voice for narrative guides to make patient instructions feel warmer and more engaging. Track usage via the dashboard to monitor character consumption per campaign.
- Attach MP3s directly to emails
- Use
ariafor narrative tone - Include text fallbacks
Creating Voice-First Experiences
Build voice-first interfaces using the OpenAI SDK with a custom base_url. Pre-generate audio for on-demand listening. Monitor rate limits (60 req/min) to ensure smooth user experiences.
Use the atlas voice for news and updates to deliver neutral, clear information. Test your integration with the free trial credit to validate audio quality and latency before full deployment.
- Use OpenAI SDK with custom base_url
- Monitor 60 req/min rate limit
- Use
atlasfor news updates
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.
