Developer Guide for Medical Text-to-Speech API

By Clinical Audio editorial team · Updated 2026-11-18

This guide details the Clinical Audio API, designed for medical teams generating large-scale patient guides and training materials. You will find precise specifications for the POST /v1/audio/speech endpoint, including required JSON fields, authentication headers, and response structures. We cover integration steps for standard HTTP clients and the OpenAI SDK, ensuring seamless compatibility with your existing infrastructure.

Learn how to manage your API key, select from eight clinical voice presets, and handle 23 languages with specific ISO code requirements. The documentation also explains rate limits, error handling, and output format options like MP3 and WAV. Use this reference to implement reliable, secure audio synthesis for healthcare communication without compromising on clarity or data privacy.

Developer Guide for Medical Text-to-Speech API

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or email and password. Accounts are created per site, and the dashboard displays your active API key, balance, and usage statistics immediately after registration.

Does the API support OpenAI SDK?

Yes. Our API mirrors the OpenAI speech endpoint structure, allowing you to use official OpenAI SDKs by setting the base_url to https://api.play79z.com/v1 and providing your Clinical Audio key. This compatibility ensures seamless integration for healthcare teams already familiar with OpenAI’s developer tools, requiring no custom SDKs or complex rewrites.

What is the base URL for the API?

The API base URL is https://api.play79z.com/v1. You send POST requests to https://api.play79z.com/v1/audio/speech for audio generation and GET requests to /v1/voices for voice and format details.

How many voices are available?

There are eight voice presets available: four female (aria, nova, luna, sage) and four male (felix, milo, atlas, orion). These voices are based on licensed recordings from LibriTTS-R and LibriVox public-domain audiobook readings.

Can I specify the language?

Yes. You can optionally provide an ISO language code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.

What audio formats are supported?

The API supports mp3, wav, opus, flac, and pcm formats. You specify the desired format using the response_format field in your JSON request body when calling the speech endpoint.

What is the rate limit?

The limit is 60 requests per minute per key. Before the first top-up, the limit is 10 requests per minute. Requests are processed sequentially, so high volume may cause queuing delays.

How do I handle errors?

Failed requests are free, and the charge is returned in full if synthesis fails. You should monitor the response status and handle network or API errors according to standard HTTP response codes.

Is there a character limit per request?

Yes, each request supports up to 4096 characters of input text. For longer texts, you must split the content into parts of this size and join the resulting audio files.

Are failed requests charged?

No. If synthesis fails, the charge is returned in full. You only pay for successfully generated audio files, with pricing at $0.01 per 1,000 characters.

Can I change my API key?

Yes, you can issue a new API key at any time. When a new key is generated, the old one stops working immediately, ensuring secure access management for your team.

Does the API support streaming?

No. The API does not support streaming, WebSocket connections, or real-time partial audio. You receive the complete audio file after the request is processed. For large texts, split the input into parts of up to 4096 characters and join the resulting audio files.

Is SSML supported?

No. The API does not support SSML, phoneme dictionaries, custom pronunciation lexicons, or emotion tags. You provide plain text input, and the system generates audio based on the specified voice and speed.

How do I generate long texts?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate request and join the resulting audio files. Typical generation speed is roughly real-time for long texts.

First request

curl

curl https://api.play79z.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.play79z.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.play79z.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

Getting your API key

Sound wave illustration for: Getting your API key

Accessing the Clinical Audio API requires a valid Bearer token generated from your account dashboard. You can sign up using Google or create a standard account with email and password on the /get-api-key/ page. Each account maintains one active key, ensuring straightforward authentication for your medical audio generation workflows.

Sign up on the dashboard

Visit the registration page to create your account. Google sign-ins receive a $0.50 trial credit valid for 7 days, while email accounts start with zero balance. Once registered, your dashboard displays your unique API key, current balance, and character usage statistics immediately.

Retrieve your Bearer token

Your API key appears on the dashboard after creation. Use this string as your Authorization: Bearer token in all requests. The key is tied to your specific site account and serves as the sole credential for authenticating your text-to-speech submissions.

Manage keys and security

Generate a new key at any time via the dashboard. When a new key is issued, the previous one stops working immediately, ensuring tight security control without downtime. This allows you to rotate credentials securely if you suspect exposure, with no service interruption.

First request with curl

Sound wave illustration for: First request with curl

Clinical Audio’s API follows the standard OpenAI speech endpoint structure, allowing you to generate medical audio files with a simple HTTP POST request. You send JSON containing your text, voice selection, and output format, receiving a direct audio file in response. This straightforward integration supports rapid prototyping and seamless embedding into existing healthcare workflows without requiring complex custom SDKs or additional dependencies.

Basic POST request example

Use the following curl command to generate speech. Replace YOUR_API_KEY with your Bearer token and adjust the voice or format as needed for your specific clinical documentation needs.

  • curl -X POST https://api.play79z.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Please take this medication twice daily with food.", "voice": "sage", "response_format": "mp3"}'

Required JSON body fields

The request body must include the model, input, and voice fields. The model parameter accepts either tts-1 or tts-1-hd, both using the same engine and pricing. The input field contains your medical text, limited to 4096 characters per request. The voice parameter selects from eight presets, such as sage for calm instructions or atlas for neutral news-style delivery.

  • model: "tts-1" or "tts-1-hd"
  • input: Text string (max 4096 chars)
  • voice: One of 8 available presets
  • response_format: mp3, wav, opus, flac, or pcm
  • speed: Optional, range 0.25–4.0

Response format and status codes

A successful request returns a 200 OK status with the audio file in the specified format. If synthesis fails, the API returns an error JSON object and the charge is refunded in full. Failed requests are free, ensuring you are not billed for unsuccessful audio generation attempts. Ensure your input text is within character limits to avoid processing errors.

First request with curl

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

To use the official OpenAI SDKs, configure the client by changing the base_url to https://api.play79z.com/v1 and providing your Bearer token. This single change directs all standard TTS requests to our infrastructure while preserving the familiar request shape.

Set base_url to our endpoint

Initialize your SDK client with the base URL https://api.play79z.com/v1. Use your unique API key for authentication. This aligns the SDK’s default endpoints with our speech generation service.

  • Base URL: https://api.play79z.com/v1
  • Auth: Authorization: Bearer tts-...

Use standard TTS methods

Call the standard audio.speech.create method. Pass your text, selected voice, and desired format exactly as you would for OpenAI. The API returns the audio file directly in the response.

Compatibility with existing code

Existing scripts using the OpenAI Python or Node.js SDKs require only the base URL adjustment. No custom client libraries are needed. You can immediately generate medical guides or training audio using your current integration logic.

  • Same JSON body shape
  • Official OpenAI SDKs work

Available voices and languages

Sound wave illustration for: Available voices and languages

Clinical Audio offers eight voice presets designed for clear medical communication. Each voice is based on licensed recordings from LibriTTS-R, sourced from LibriVox public-domain audiobook readings. Every generated file carries an inaudible watermark identifying it as synthetic speech.

8 presets for clinical tones

Select a preset that matches your content’s tone. Female voices include Aria (warm, clear narrator), Nova (bright, upbeat), Luna (soft, storytelling), and Sage (calm, instructional). Male options are Felix (energetic, promo), Milo (friendly, conversational), Atlas (neutral, news), and Orion (deep, documentary).

23 supported languages

Any voice can speak any of the 23 supported languages: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.

Language code specification

If the language parameter is omitted, the system guesses the language from the script. Latin script text defaults to English. For non-English Latin-script text, explicitly set the language field to ensure accurate synthesis.

Output formats and speed

Sound wave illustration for: Output formats and speed

Clinical Audio returns audio in MP3, WAV, Opus, FLAC, or PCM formats via the response_format parameter. The choice depends on your integration needs, balancing file size and compatibility for patient guides or training modules.

The speed parameter accepts values between 0.25 and 4.0, allowing you to adjust playback rate while synthesis occurs. Generation typically takes a few seconds for short phrases, scaling to roughly real-time for longer texts.

MP3, WAV, Opus, FLAC, PCM

Select your preferred format in the request body. MP3 offers broad compatibility, while WAV, FLAC, and PCM provide uncompressed or lossless options. Opus is efficient for low-bandwidth delivery.

  • mp3, wav, opus, flac, pcm

Speed range from 0.25 to 4.0

Adjust speech rate from 0.25x to 4.0x. Slower speeds may aid comprehension in medical instructions, while faster rates suit quick reference materials. Requests are processed sequentially, so higher speeds may queue under load.

Choosing the right format

Use MP3 for general web playback. Choose WAV or FLAC for archival clarity. Select PCM for raw data processing. Opus is suitable for efficient streaming. Format does not affect pricing or character limits.

Output formats and speed

Rate limits and quotas

Sound wave illustration for: Rate limits and quotas

Clinical Audio enforces a strict rate limit of 60 requests per minute per API key. This cap applies to all synthesis jobs, ensuring stable performance for healthcare teams generating large volumes of patient guides or training materials. Requests are processed sequentially, so sustained high usage may introduce slight queuing delays during peak times.

60 requests per minute per key

Your single API key allows up to 60 synthesis requests every minute. If you exceed this threshold, additional requests will be rejected until the window resets. For teams requiring higher throughput, consider distributing load across multiple keys or implementing client-side queuing to stay within the limit.

10 requests before first top-up

New accounts start with a reduced quota of 10 requests per minute. This lower limit applies until you complete your first top-up. Once you add credit via USDT (TRC-20), your full 60 requests-per-minute capacity is immediately unlocked, allowing you to scale your audio generation workflow without interruption.

Handling rate limit errors

When you exceed the limit, the API returns a 429 Too Many Requests status code. Implement exponential backoff in your integration to retry after a short delay. Failed requests due to rate limits do not consume your character credit, ensuring you do not pay for rejected attempts.

  • Status code 429 indicates a rate limit hit
  • Retry after a brief exponential backoff period
  • Rejected requests do not deduct from your balance

Error handling and retries

Sound wave illustration for: Error handling and retries

API responses include standard HTTP status codes to indicate success or failure. Understanding these codes allows your integration to handle transient issues without manual intervention, ensuring that audio generation pipelines continue processing patient guides or training materials without interruption.

Common error codes

A 401 Unauthorized error indicates an invalid or expired API key. A 429 Too Many Requests signal means you have exceeded the rate limit of 60 requests per minute. A 500 Internal Server Error suggests a temporary issue with the synthesis engine.

  • 401: Invalid authentication token
  • 400: Missing required fields like input or voice
  • 429: Rate limit exceeded
  • 500: Internal synthesis failure

Best practices for retries

Implement exponential backoff for 429 and 500 errors to avoid overwhelming the queue. Retrying immediately often fails if the server is still processing previous requests. For 401 errors, verify your key in the dashboard before retrying.

Failed request refunds

If synthesis fails, the charge is returned in full. This ensures you only pay for successfully generated audio files. Check the response status to confirm whether a charge was applied.

Error handling and retries

Model specifications

Sound wave illustration for: Model specifications

Clinical Audio offers two model identifiers, tts-1 and tts-1-hd, which utilize the identical underlying synthesis engine. Both models deliver the same vocal quality and support all eight voice presets and 23 languages. The distinction lies solely in the identifier used in your API requests, allowing you to switch between them without changing your voice configuration or language settings.

Pricing remains consistent at $10 per million characters regardless of which model you select. There is no price premium for tts-1-hd, and no performance difference in generation speed. This uniformity simplifies billing and integration for healthcare teams managing large volumes of patient guides or training materials without needing to optimize for specific model tiers.

Same engine and price

Both models run on the same core engine, ensuring identical voice characteristics and output quality. You can use either tts-1 or tts-1-hd in your requests without affecting the audio result. This allows for straightforward API updates or future-proofing without altering your voice parameters or incurring different costs.

  • Identical synthesis engine
  • Same voice presets and languages
  • $0.01 per 1,000 characters for both

Character limit of 4096

Each API request supports a maximum of 4,096 characters in the input field. This limit applies to the text payload, including spaces and punctuation. For longer medical documents or extended training scripts, you must split the text into chunks of up to 4,096 characters. Generate audio for each chunk individually and join the resulting files to create the complete audio guide.

This character limit ensures consistent processing times and reliable delivery. Short phrases typically generate in a few seconds, while longer texts process at roughly real-time speed. Managing chunk sizes within this limit helps maintain predictable latency during high-volume synthesis workflows.

  • Max 4,096 characters per request
  • Spaces and punctuation count
  • Split and join for longer texts

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Our patient guides simplify complex medical information for large teams to deliver clear and compassionate care.

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. openai-python on GitHub
  3. TRON developer hub: TRC-20
  4. openai-node on GitHub
  5. MDN: Web Speech API
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. LibriTTS-R corpus (OpenSLR 141)
  8. IETF RFC 7845: Ogg Opus
  9. curl documentation
  10. LibriVox public-domain audiobooks
  11. Node.js documentation
  12. OpenAI API reference: create speech

More on this site