API Documentation for Patient Guide Audio

By VoxMedica editorial team · Updated 2026-11-19

This documentation helps healthcare developers integrate our text-to-speech API into patient education platforms. You will learn how to send text via a familiar OpenAI-compatible endpoint and receive clear audio files for guides, instructions, and informational content.

We cover essential integration details including authentication, voice selection, and rate limits. The guide explains how to handle text length constraints and format audio outputs, ensuring your startup can deliver reliable synthetic speech without complex enterprise contracts.

API Documentation for Patient Guide Audio

Frequently asked questions

What is the base URL?

The base URL is https://api.9a9993.info/v1. You use this endpoint for all API calls, including generating speech and retrieving voice details. It follows the standard OpenAI-compatible structure.

Can I use the OpenAI Python SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.9a9993.info/v1. You can use the same request shape as the OpenAI speech endpoint, simply providing your VoxMedica API key for authentication in your Python code.

How do I set the API key?

Include your key in the Authorization header as 'Bearer tts-...'. You receive one active key per account on the /get-api-key/ page. Ensure you pass this header with every request to authenticate your usage against your account balance.

What models are available?

Two models are available: 'tts-1' and 'tts-1-hd'. Both use the same engine and pricing. You can list all available models by sending a GET request to /v1/models.

Is SSML supported?

No, SSML is not supported. The API accepts plain text input up to 4096 characters. You cannot use phoneme dictionaries or custom pronunciation lexicons. For precise control, split your text and adjust speed or voice selection manually in your code.

What is the max text length?

The maximum input length is 4096 characters per request. For longer texts, you must split them into parts of up to 4096 characters and join the resulting audio files. Spaces and punctuation count toward this character limit.

How do I handle errors?

Failed requests are free, and the charge is returned in full if synthesis fails. Check the response status code to determine success or failure.

What formats can I receive?

You can receive audio in mp3, wav, opus, flac, or pcm formats. Specify your preferred format using the response_format field in your POST request body. This allows you to choose the best balance between file size and quality for your application.

Can I change speed?

Yes, you can adjust the speed between 0.25 and 4.0. Use the speed parameter in your request body to make the voice speak faster or slower. This is useful for adapting audio length for patient education materials or quick updates.

Is there a WebSocket option?

No, there is no WebSocket or streaming option. Audio is generated synchronously and returned in the response. Requests are processed one after another, so under load, a request may wait in a queue before synthesis begins.

How do I rotate my key?

A new key can be issued any time from your account page. When you generate a new key, the old one stops working immediately. This ensures secure access control without needing to manage multiple active credentials simultaneously.

What happens on rate limit?

The limit is 60 requests per minute per key. Before the first top-up, it is 10 per minute. If you exceed the limit, requests may be delayed or rejected. Monitor your usage on the dashboard to avoid interruptions during high-volume generation.

Is there a Node.js SDK?

There is no official SDK of our own, but you can use the official OpenAI Node.js SDK. Simply configure the base_url to https://api.9a9993.info/v1.

Do I need a custom client?

No, you do not need a custom client. You can use the OpenAI SDK or plain HTTP requests. The API follows standard conventions, so any HTTP library capable of sending JSON POST requests and handling Bearer authentication will work correctly.

First request

curl

curl https://api.9a9993.info/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.9a9993.info/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.9a9993.info/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

Quickstart with Curl

Sound wave illustration for: Quickstart with Curl

VoxMedica’s API mirrors the familiar OpenAI structure, allowing healthcare developers to integrate patient guide audio quickly. Use standard HTTP tools to send text and receive clear speech files for educational materials.

Install curl

Install curl

Ensure curl is installed on your system. It is the standard tool for sending HTTP requests in terminal environments, perfect for testing your first synthesis.

Send your first request

Send your first request

Use POST https://api.9a9993.info/v1/audio/speech with your Bearer token. Include model (tts-1 or tts-1-hd), input (up to 4096 characters), and a voice preset like aria or atlas.

  • Authorization: Bearer tts-...
  • Content-Type: application/json

Receive audio file

The API returns the audio file directly in the response body. Supported formats include mp3, wav, opus, flac, and pcm. Failed requests incur no charge.

OpenAI SDK Compatibility

Sound wave illustration for: OpenAI SDK Compatibility

VoxMedica’s TTS API mirrors the OpenAI speech endpoint structure, allowing healthcare developers to integrate audio generation without rewriting their existing code logic. By simply adjusting the base URL, you can leverage the same SDKs you already know for patient education workflows.

This compatibility reduces friction for startups building medical apps or digital guide platforms. You continue using familiar libraries while gaining access to our specific voice presets and pricing model tailored for clear, compliant audio outputs.

Change base_url

Update your SDK configuration to point to https://api.9a9993.info/v1 instead of the default OpenAI endpoint. This single change directs all subsequent requests to our infrastructure.

Ensure your API key is valid for this domain. The key format remains identical, but it authenticates against VoxMedica’s billing and rate-limit systems.

  • Base URL: https://api.9a9993.info/v1
  • No changes to method or path: /v1/audio/speech

Use official SDKs

The official OpenAI SDKs for Python, Node.js, and other languages work out of the box. Just configure the client with our base URL and your Bearer token.

This approach lets you maintain your current development stack while switching providers, ideal for teams that already have integration scaffolding in place.

Same request shape

The JSON body requires model, input, voice, and response_format. These fields map directly to the standard OpenAI speech parameters, ensuring predictable behavior.

Speed and language parameters are also supported, allowing you to fine-tune the audio for patient comprehension without adapting to a new API schema.

Request Parameters

Sound wave illustration for: Request Parameters

Configure your TTS requests by selecting the engine model, choosing a voice preset that fits your patient guide’s tone, and adjusting the playback speed. These three parameters define how your medical text is rendered into clear audio.

Start with "tts-1" for standard quality or "tts-1-hd" for higher fidelity. Both engines are priced identically at $0.01 per 1,000 characters, allowing you to choose based on your clarity needs without extra cost.

Model selection

Use "tts-1" for standard generation or "tts-1-hd" for enhanced clarity. Both models use the same underlying engine and incur the same rate, so you can switch freely without changing your billing expectations.

  • "tts-1": Standard quality, optimized for speed.
  • "tts-1-hd": Higher fidelity.

Voice presets

Choose from eight licensed voices, such as Aria for warm narration or Atlas for neutral, news-style delivery. Each voice supports all 23 languages; specify the language code to ensure correct pronunciation for non-English content.

  • Aria: Warm, clear narrator.
  • Atlas: Neutral, news-style.
  • Supports 23 languages.

Speed control

Adjust the speed parameter between 0.25 and 4.0 to fit your audience’s listening preferences. Slower speeds improve comprehension for complex instructions, while faster speeds reduce generation time for long texts.

  • Range: 0.25 to 4.0.
  • Default speed is 1.0.

Audio Formats

Sound wave illustration for: Audio Formats

Choose the format that best fits your patient education workflow. We support standard audio types to ensure compatibility with most medical devices and web players.

MP3 support

MP3 is the default and most widely supported format. It offers a good balance between file size and quality, making it ideal for web-based patient guides and mobile apps.

WAV format

WAV provides uncompressed audio.

Opus and FLAC

Opus offers excellent compression for smaller file sizes with good quality, suitable for bandwidth-constrained environments. FLAC provides lossless compression, preserving audio quality while reducing storage needs compared to WAV.

  • Opus: efficient for streaming and mobile use
  • FLAC: lossless

Authentication

Sound wave illustration for: Authentication

Secure your audio generation requests with a simple Bearer token in the HTTP header. This standard authentication method ensures that only your authorized account can consume credits and generate patient guide audio files.

Bearer token

Include your API key as a Bearer token in every request header. Use the format Authorization: Bearer tts-... to authenticate your requests against the API endpoint.

API key format

Each account holds one active key. Keys begin with the prefix tts- and are unique to your account. You can find your current key on the /get-api-key/ dashboard page.

Key rotation

You can issue a new key at any time from your dashboard. When a new key is generated, the previous one stops working immediately, ensuring no overlap or confusion during rotation.

Authentication

Rate Limits

Sound wave illustration for: Rate Limits

VoxMedica enforces a rate limit of 60 requests per minute per API key. This limit applies to all endpoints and ensures stable generation for your patient education workflows. Each request counts toward this quota, regardless of the audio format or voice selected.

60 requests per minute

Once your key is active, you can send up to 60 synthesis requests within any one-minute window. Exceeding this limit will result in a 429 error until the window resets.

  • Limit is per key, not per account.
  • Applies to all request types.

New key limits

Newly created keys start with a lower limit of 10 requests per minute. This applies until you make your first top-up or purchase. After the first top-up, the limit increases to the standard 60 requests per minute. This helps prevent abuse during the trial or initial usage phase.

  • Starts at 10 requests/minute.
  • Increases to 60 after first top-up.

Queue behavior

Requests are processed sequentially within the rate limit. If you send multiple requests simultaneously, they are queued and processed one after another. Longer texts may take additional time to generate, so plan your integrations accordingly to avoid delays in your delivery pipeline.

Error Handling

Sound wave illustration for: Error Handling

Synthetic audio generation can occasionally fail. Our API returns standard HTTP status codes to help you diagnose the issue quickly, ensuring you know exactly when a request did not complete.

Common error codes

Use 400 for invalid parameters (e.g., text exceeding 4096 characters) and 401 for authentication failures. A 429 indicates you have hit the rate limit of 60 requests per minute.

Retry strategy

Implement exponential backoff for 429 and 500 errors. Since requests are processed sequentially, short waits often resolve queue congestion. Avoid rapid-fire retries to prevent additional rate limit penalties.

Free failed requests

If synthesis fails, the charge is returned in full. You only pay for successfully generated audio files, making trial runs and error recovery cost-free.

Text Length Limits

Sound wave illustration for: Text Length Limits

Our API processes text in discrete chunks, limiting each request to 4,096 characters. This constraint ensures consistent synthesis quality for patient education materials, from brief dosage instructions to detailed procedure explanations.

4096 characters max

Each API call accepts a maximum of 4,096 characters for the input field. Spaces, punctuation, and special characters count toward this limit. For lengthy medical guides, you must divide the content into manageable segments before sending requests.

  • Count every character, including spaces and punctuation.
  • Limit is per request, not per document.

Splitting long texts

To handle extensive documents, split your text into parts of up to 4,096 characters. Ensure logical breaks, such as sentence ends, to maintain natural audio flow when segments are combined. This approach prevents truncation and maintains clarity for patients.

Joining audio files

After receiving separate audio files for each text segment, you must join them to create a complete guide. The API returns distinct audio files for each request; combining them into a single file is your responsibility using standard audio tools.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This consistency helps you predict costs for large volumes of patient guides or appointment reminders without tracking tiered usage.

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. W3C WAI: making audio and video accessible
  3. IETF RFC 7845: Ogg Opus
  4. FFmpeg documentation
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. Tether (USDT)
  7. TRON developer hub: TRC-20
  8. MDN: Web Speech API
  9. LibriVox public-domain audiobooks
  10. OpenAI API reference: create speech
  11. openai-python on GitHub
  12. Python documentation

More on this site