Integrate Medical Text-to-Speech with Our API

By MediVoice editorial team · Updated 2026-11-18

This guide helps clinical and administrative teams integrate MediVoice’s text-to-speech API into their existing workflows. You will find precise technical details for generating clear audio from medical texts, patient guides, and educational scripts using standard HTTP requests or the OpenAI SDK.

Learn how to authenticate securely, manage API keys, and handle voice parameters like speed and language. We cover practical integration steps, rate limits, and error handling so you can reliably convert large volumes of medical documentation into accessible audio without managing complex infrastructure.

Integrate Medical Text-to-Speech with Our API

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.mp3

Python (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
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication and Keys

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

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

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

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

Sound wave illustration for: 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-1 for standard cost or tts-1-hd for higher quality.
  • Specify aria for a warm, clear narrator tone suitable for patient instructions.
  • Set response_format to mp3 for 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, and response_format.
  • Optional: speed (0.25–4.0) and language (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

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

Sound wave illustration for: 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
Audio Formats and Options

Rate Limits and Quotas

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

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

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

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. Python documentation
  3. LibriVox public-domain audiobooks
  4. MDN: Web Speech API
  5. openai-node on GitHub
  6. TRON developer hub: TRC-20
  7. Creative Commons Attribution 4.0
  8. LibriTTS-R corpus (OpenSLR 141)
  9. OpenAI API reference: create speech
  10. FFmpeg documentation
  11. W3C WAI: making audio and video accessible
  12. ISO 639 language codes

More on this site