API Documentation for Medical TTS Integration

By MediVoice editorial team · Updated 2026-11-18

This documentation outlines the integration of the MediVoice API, a reliable text-to-speech solution designed for healthcare startups creating patient guides and multilingual medical content. You will find precise technical details for generating clear, accessible audio from clinical instructions in Hindi and 22 other languages, including specific parameters for voice selection and language codes.

The guide covers authentication, endpoint structures, and rate limits, ensuring seamless implementation into your existing workflows. By following these specifications, you can efficiently convert up to 4,096 characters of text into high-quality audio files, supporting your startup’s need for accurate, compliant, and scalable medical communication tools.

API Documentation for Medical TTS Integration

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

Python (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
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

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

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

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

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

Sound wave illustration for: 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 model as tts-1 or tts-1-hd for 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

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

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

Rate Limits and Quotas

Error Handling

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

Sound wave illustration for: 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_KEY with your secret key.
  • Adjust the input field 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_url to the MediVoice API endpoint.
  • Use the Audio model 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

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

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. Tether (USDT)
  3. IETF RFC 7845: Ogg Opus
  4. Node.js documentation
  5. W3C WAI: making audio and video accessible
  6. MDN: Web Speech API
  7. Python documentation
  8. Creative Commons Attribution 4.0
  9. openai-node on GitHub
  10. ISO 639 language codes
  11. OpenAI API reference: create speech
  12. FFmpeg documentation

More on this site