Integration Guide for Medical Text-to-Speech API

By MediSpeak editorial team · Updated 2026-11-19

This guide details the integration of the MediSpeak text-to-speech API, designed for product teams building patient education platforms. You will find precise specifications for the speech endpoint, including request parameters, authentication methods, and response formats. The documentation provides concrete examples using cURL and the OpenAI SDK, enabling engineers to implement reliable audio generation without managing complex infrastructure or custom voice models. (Note: The site does not offer custom voice models, but the OpenAI SDK is a third-party library, not an official SDK from MediSpeak.)

The reference covers critical operational details such as the 4096-character input limit, rate limits of 60 requests per minute, and character-based pricing. You will also learn how to handle long medical texts by splitting and joining audio segments, manage API keys, and interpret standard error codes. This page serves as the complete technical reference for integrating MediSpeak into healthcare applications, ensuring predictable performance and clear licensing for synthetic audio outputs.

Integration Guide for Medical Text-to-Speech API

Frequently asked questions

What is the base URL?

The API base URL is https://api.pj88.info/v1. You send POST requests to https://api.pj88.info/v1/audio/speech. This endpoint accepts JSON bodies with text, voice, and format parameters. The request shape matches the OpenAI speech endpoint, allowing you to use official OpenAI SDKs by simply changing the base_url configuration.

How do I set the language?

Include the optional language field in your request body using an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, you must explicitly set the language field to ensure accurate synthesis.

Can I change the speed?

Yes, use the speed parameter with a value between 0.25 and 4.0. This allows you to adjust the playback rate of the generated audio. The default speed is 1.0. Adjusting speed affects the duration of the output audio file while maintaining the selected voice characteristics.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key. If you exceed this, requests may queue or fail. Before your first top-up, the limit is 10 requests per minute. Failed requests are free, but successful ones incur charges. Monitor your usage via the dashboard to avoid delays.

Is the response streaming?

No, the response is not streaming. You receive the complete audio file in the response body after synthesis finishes. Requests are processed sequentially, so under load, a request may wait in a queue. Requests are processed sequentially, so under load, a request may wait in a queue. Typical speed is roughly real time for long texts, but short phrases take a few seconds.

Do I need to handle JSON manually?

No, you do not need to handle JSON manually if you use the official OpenAI SDKs. Simply change the base_url to https://api.pj88.info/v1 and provide your API key. Simply change the base_url to https://api.pj88.info/v1 and provide your API key. The SDK handles the JSON serialization and deserialization for you, making integration straightforward for existing OpenAI workflows.

How do I know which voice to use?

Check the GET /v1/voices endpoint for the full list of eight presets. Options include female voices like aria, nova, luna, and sage, or male voices like felix, milo, atlas, and orion. Each voice has a distinct tone, such as warm, upbeat, soft, or neutral, suitable for different content types.

What is the tts-1-hd model?

The tts-1-hd model is one of the two available models, alongside tts-1. Both use the same engine and have the same price of $10 per 1 million characters. The model field accepts either value, allowing you to choose based on your quality preference. Both models use the same engine and price.

First request

curl

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

Authentication

Sound wave illustration for: Authentication

Authentication relies on a single active Bearer token per account. Pass your key via the Authorization: Bearer <key> header in every request. MediSpeak issues one key per site account, ensuring straightforward access control for your integration.

Keys are managed via the /get-api-key/ dashboard. You can generate a new key at any time, which immediately invalidates the previous one. This ensures only one active credential exists. Keys are managed via the /get-api-key/ dashboard.

Bearer token format

Bearer token format

Use the format Authorization: Bearer tts-... where the ellipsis represents your unique key string. The key must be included in the HTTP header of every API call to the /v1/audio/speech endpoint. No additional authentication layers or scopes are required.

Key management

Key management

Your active key and usage stats are visible on the /get-api-key/ page. You can issue a replacement key at any time. The old key stops working immediately upon generation of the new one, ensuring clean rotation without downtime for active requests in flight.

  • Generate new keys instantly
  • Old keys invalidate immediately
  • Single active key per account

Revoking old keys

Revocation is automatic. When you generate a new key from the dashboard, the previous key becomes invalid instantly. There is no delay or grace period. This allows you to rotate credentials securely without needing to manually blacklist old tokens in your infrastructure.

Quickstart with cURL

Sound wave illustration for: Quickstart with cURL

Send a POST request to https://api.pj88.info/v1/audio/speech with your bearer token and JSON payload to generate audio instantly. The API returns the audio file directly in the response body for immediate use in your patient education workflows.

Ensure your input text does not exceed 4096 characters per request. For longer medical guides, split the text into chunks and concatenate the resulting audio files to maintain continuity.

Basic request example

Use the following cURL command to generate speech. Replace YOUR_API_KEY with your token from the dashboard. The example uses the 'nova' voice in English.

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

Response format

On success, the response contains the audio binary data with the appropriate content type (e.g., audio/mpeg). The file is ready for playback or storage immediately upon receipt.

Error handling

If synthesis fails, you receive a JSON error object describing the issue, such as invalid characters or missing fields. Failed requests are free. Failed requests are free, so your balance remains unaffected.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

MediSpeak’s API mirrors the OpenAI speech endpoint structure, allowing teams to reuse existing OpenAI SDKs with minimal configuration. By updating the base URL, you can leverage familiar libraries for authentication and request handling without learning a new client pattern.

This compatibility ensures that your healthcare product team can integrate TTS into patient education workflows using standard engineering practices. The SDK handles the HTTP transport, letting you focus on voice selection and text processing for clinical materials.

Base URL configuration

Set the SDK’s base URL to https://api.pj88.info/v1. This directs all speech synthesis requests to MediSpeak’s infrastructure while maintaining the standard OpenAI request shape.

SDK compatibility

The official OpenAI SDKs work directly because the request and response schemas are identical. You only need to adjust the base URL and provide your MediSpeak Bearer token. You only need to adjust the base URL and provide your MediSpeak Bearer token.

Code snippet

Use the OpenAI Python library to generate audio. Initialize the client with your API key and the custom base URL, then call the audio.speech.create method.

  • Install: pip install openai
  • Set API key: os.environ["OPENAI_API_KEY"] = "tts-your-key"
  • Configure base URL: https://api.pj88.info/v1
  • Method: audio.speech.create(model="tts-1", voice="aria", input="Patient instructions...")

Request Parameters

Sound wave illustration for: Request Parameters

Configure synthesis behavior via model, voice, and speed parameters. Select the engine and audio persona that best fits clinical or educational content.

Adjust generation speed between 0.25x and 4.0x to match listener comprehension needs. Use language to override auto-detection for non-English Latin scripts.

Model selection

Choose between "tts-1" and "tts-1-hd". Both use the same engine and pricing, so select based on your quality preference without cost impact.

Voice presets

Select from eight licensed presets optimized for clarity. Female voices include Aria, Nova, Luna, and Sage; male voices include Felix, Milo, Atlas, and Orion. All support 23 languages. Any voice can speak any of these languages.

  • Aria: warm, clear narrator
  • Nova: bright, upbeat
  • Luna: soft, storytelling
  • Sage: calm, instructional
  • Felix: energetic, promo
  • Milo: friendly, conversational
  • Atlas: neutral, news
  • Orion: deep, documentary

Speed control

Set speed from 0.25 to 4.0. Slower rates improve comprehension for complex medical terminology, while faster rates suit routine updates.

Response Formats

Sound wave illustration for: Response Formats

MediSpeak supports five audio formats for synthesized patient education materials. The API returns raw audio bytes, allowing you to save the response directly to your application’s storage. (Note: The API does not support streaming; the entire file is returned after synthesis.)

MP3 output

MP3 is the default format, offering high compatibility across all web browsers and mobile health applications. It provides efficient compression suitable for general patient instructions.

  • Default response format
  • Universal browser compatibility
  • Efficient file size for mobile networks

WAV output

WAV provides uncompressed, lossless audio ideal for clinical records or archiving where bit-perfect fidelity is required. It is suitable for integration with electronic health record (EHR) systems that mandate lossless audio inputs.

  • Lossless audio quality
  • Ideal for EHR archiving
  • No compression artifacts

OPUS and FLAC options

OPUS offers superior compression efficiency for low-bandwidth environments, maintaining clarity for voice notes. FLAC provides lossless compression, reducing storage costs compared to WAV while preserving exact audio data for regulatory compliance.

  • OPUS: High efficiency, low bandwidth
  • FLAC: Lossless compression
  • Optimized for storage costs
Response Formats

Rate Limits

Sound wave illustration for: Rate Limits

The API enforces a standard rate limit of 60 requests per minute per key. This allows product teams to generate patient education audio efficiently without overwhelming the service, supporting steady integration workflows.

New accounts start with a restrictive 10 requests per minute limit. This prevents abuse during the initial phase. The limit increases to 60 req/min automatically after the first successful top-up of at least $5.

Requests are processed sequentially. Under load, additional requests wait in a queue rather than failing immediately. This ensures reliable delivery of audio files, though generation time may extend slightly during high demand periods.

60 requests per minute

Each API key supports up to 60 requests per minute. This capacity is sufficient for most healthcare product integrations, allowing batch processing of patient guides. Requests are processed sequentially, so under load, a request may wait in a queue.

Initial 10 req/min limit

New keys begin with a 10 requests per minute limit. This restriction applies until the account records its first top-up transaction. Once a minimum $5 deposit is confirmed via USDT, the limit automatically increases to 60 req/min.

  • Applies only to newly created keys

Queue behavior

Requests are processed in the order received. If the limit is exceeded, subsequent requests enter a queue. They are executed sequentially as slots become available. This prevents data loss but may increase total latency for large batches.

Handling Long Texts

Sound wave illustration for: Handling Long Texts

The API enforces a strict 4096-character limit per request, which requires client-side segmentation for longer patient education materials. This constraint ensures predictable processing times and consistent audio quality for each segment.

Clients must split input text into chunks not exceeding 4096 characters, including spaces and punctuation. Each chunk generates a separate audio file that requires programmatic concatenation to form the final output.

4096 character split

Send each text segment as a separate POST request. The system does not handle multi-part payloads internally. Clients must split input text into chunks not exceeding 4096 characters.

Ensure segment boundaries respect word breaks to avoid unnatural pauses in the generated speech.

  • Maximum input length: 4096 characters per request
  • Limit applies to the raw input string, including spaces and punctuation
  • No automatic splitting; logic resides in your integration

Audio joining

Concatenate the returned audio files sequentially using your preferred library (e.g., FFmpeg, PyDub).

Maintain the original order of segments to preserve the narrative flow of the medical guide.

Character counting

Count characters accurately before sending requests, as the limit is strict. Failed requests do not consume credit, but valid requests do.

Include spaces and punctuation in your character count to prevent 400 errors.

Error Codes

Sound wave illustration for: Error Codes

The API returns standard HTTP status codes to indicate request outcomes. Understanding these responses allows product teams to implement robust error handling within their patient education workflows without unnecessary retries.

400 Bad Request

This error indicates that the request body is malformed or missing required fields. Common causes include exceeding the 4096 character limit for the input field or providing an invalid voice preset. Ensure your input text is within limits and your voice ID matches one of the eight available presets.

  • Check input length does not exceed 4096 characters.
  • Verify voice is one of the 8 supported presets.
  • Ensure response_format is one of mp3, wav, opus, flac, or pcm.

429 Rate Limit

You have exceeded the allowed request rate for your API key. New accounts start with a limit of 10 requests per minute, which increases to 60 requests per minute after the first top-up. When this limit is reached, subsequent requests will receive a 429 status code until the window resets.

  • Default limit: 10 requests/minute.
  • Post-top-up limit: 60 requests/minute.
  • Implement exponential backoff for retries.

500 Server Error

A 500 error indicates an unexpected condition on our side during synthesis. If synthesis fails, the charge is returned in full. Retrying the request is safe, as failed requests do not incur character costs. If the issue persists, contact support via email.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Medical product teams need predictable budgets for patient education materials.

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

More on this site