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.mp3Python (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 | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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
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
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
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
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
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
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

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
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
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
inputlength does not exceed 4096 characters. - Verify
voiceis one of the 8 supported presets. - Ensure
response_formatis 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.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- curl documentation
- LibriTTS-R paper (arXiv 2305.18802)
- openai-node on GitHub
- Creative Commons Attribution 4.0
- ISO 639 language codes
- Python documentation
- OpenAI API reference: create speech
- LibriVox public-domain audiobooks
- TRON developer hub: TRC-20
- LibriTTS-R corpus (OpenSLR 141)
- MDN: Web Speech API
