How to Generate Audio from Medical Text for Patient Guides?

By MediVoice editorial team · Updated 2026-11-18

We cover practical steps for configuring requests, handling responses, and optimizing for team usage. You will also find details on security, error handling, and common pitfalls specific to medical content. By following these instructions, your team can integrate reliable speech synthesis into patient portals or email guides with minimal friction.

How to Generate Audio from Medical Text for Patient Guides?

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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
Optimizing for Large Teams

Security and Data Privacy

Sound wave illustration for: 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

Sound wave illustration for: 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-1 or tts-1-hd models.
  • 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 language parameter for non-English text.
  • Verify synthetic watermark presence.
  • Confirm requested audio format (mp3, wav, opus, flac, pcm).

Support and Documentation

Sound wave illustration for: 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

Sound wave illustration for: 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 language explicitly 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

Sound wave illustration for: 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-1 model 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 aria for 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 atlas for 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.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. MDN: Web Speech API
  3. FFmpeg documentation
  4. W3C WAI: making audio and video accessible
  5. openai-python on GitHub
  6. openai-node on GitHub
  7. ISO 639 language codes
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. Tether (USDT)
  10. curl documentation
  11. Creative Commons Attribution 4.0
  12. LibriVox public-domain audiobooks

More on this site