Frequently asked questions
How do I get my API key?
Sign up on the /get-api-key/ page using Google or email. Your API key appears on that page along with your balance and usage details. You can issue a new key at any time, which stops the old one immediately. This process is specific to the playmk77.com account.
What is the base URL for the API?
The API base URL is https://api.playmk77.com/v1. Use this for all requests, including the speech endpoint at /v1/audio/speech. Other endpoints like /v1/voices and /v1/models also use this base URL. Ensure your SDK configuration points to this exact address for proper connectivity.
Can I use the OpenAI Python SDK?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.playmk77.com/v1. Use the standard speech endpoint with your MindVoice API key. This allows you to leverage existing code structures without needing a custom SDK. Just update the configuration to point to our API.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key, or 10 per minute before the first top-up. Exceeding this may cause requests to wait in a queue or fail. Requests are processed sequentially, so under load, you might experience delays. Monitor your usage to stay within limits.
How do I specify the voice in the request?
Include the voice field in your JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narration to deep documentary styles. The voice determines the audio character of the generated speech.
Can I change the speed of the generated audio?
Yes, use the speed field with a value between 0.25 and 4.0. This allows you to adjust the playback rate of the synthesized speech. Faster speeds reduce generation time, while slower speeds may enhance clarity for meditation or instructional content. Adjust this parameter to fit your content needs.
What is the maximum text length per request?
The maximum input text length is 4096 characters per request. For longer texts, split them into parts of this size and join the resulting audio files. Spaces and punctuation count toward the character limit. This ensures efficient processing and maintains audio quality for your generated content.
How do I handle failed requests?
Failed requests are free; the charge is returned in full if synthesis fails. You do not lose credit for unsuccessful attempts. Check the response status to identify failures and retry if necessary. This policy ensures you only pay for successfully generated audio files.
Is the API key case-sensitive?
The documentation does not explicitly state case sensitivity for the API key. Ensure you copy the key exactly as displayed on your /get-api-key/ page, including all characters and symbols.
Can I use the same key for multiple projects?
Yes, you can use the same API key for multiple projects. Each account has one active key. If you need separate tracking, you can issue a new key, which invalidates the old one immediately.
How do I rotate my API key?
You can issue a new key at any time from the /get-api-key/ page. When you generate a new key, the old one stops working immediately. This allows for seamless rotation without downtime. Use the new key in your applications to continue service without interruption.
What happens to the old key when I generate a new one?
The old key stops working immediately when you generate a new one. This ensures that only the current key is active. You can use the new key in your applications right away. This instant invalidation helps maintain security and control over your API access.
Does the API support async requests?
The API does not support async requests or WebSocket streaming. Requests are processed sequentially, and audio is returned after generation. For long texts, you must split the input and join the audio files manually. This synchronous approach ensures reliable delivery of each audio file.
How do I check available voices programmatically?
Send a GET request to /v1/voices to retrieve available voices, languages, formats, and pricing. This endpoint provides the list of eight presets and their details. Use this information to dynamically select voices in your application based on the content type or user preference.
First request
curl
curl https://api.playmk77.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.playmk77.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.playmk77.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 | |
|---|---|
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, issued via the /get-api-key/ dashboard. This key authorizes all requests to the API base URL and replaces any previous key immediately upon rotation. Keep it secure, as it represents your entire account access.
The token format is tts- followed by alphanumeric characters. It must be included in the Authorization header of every request. If you lose your key, generate a new one from your dashboard; the old one stops working instantly.
API Key Format
Your API key starts with the prefix tts- and contains a unique identifier. It is generated when you sign up or create a new key in your account dashboard. There is only one active key per account at any time.
- Format:
tts-XXXXXXXXXXXXXXXXXXXXXXXX - Single active key per account
- Visible only in the dashboard during creation
Bearer Token
Include your key in the HTTP Authorization header as a Bearer token. This standard method ensures secure transmission of your credentials with every API call. Use Authorization: Bearer tts-... for all endpoints.
- Header:
Authorization: Bearer tts-... - Required for all requests
- Case-sensitive prefix
tts-
Key Rotation
You can issue a new key at any time from your dashboard. The new key becomes active immediately, and the previous key stops working at once. This is useful if you suspect a key has been exposed or for regular security maintenance. There is no downtime during rotation.
- Generate new key anytime
- Old key stops instantly
- No downtime during rotation
First Request
Send a POST request to the speech endpoint to generate audio from text. The API accepts standard JSON bodies, mirroring the OpenAI speech endpoint structure for easy integration.
You can test the integration immediately using the provided cURL command. Replace the placeholder API key with your unique credential from the dashboard to receive your generated audio file.
cURL Example
Use this command to send your first request. Ensure you replace YOUR_API_KEY with the key issued to your account.
curl -X POST https://api.playmk77.com/v1/audio/speech \\-H "Authorization: Bearer YOUR_API_KEY" \\-H "Content-Type: application/json" \\- ` -d '{"model": "tts-1", "input": "Breathe in calm.", "voice": "luna", "response_format": "mp3"}'`
JSON Body
The request body requires the model, input text, and voice parameters. You may optionally specify response_format and speed. The text input must not exceed 4096 characters.
model: "tts-1" or "tts-1-hd"
Response Format
A successful request returns the audio file directly in the response body. If synthesis fails, you receive a standard error JSON with details on the failure.

OpenAI SDK Integration
Integrating MindVoice with the OpenAI SDK is straightforward because the API endpoint mirrors the standard speech schema. You only need to redirect the base URL to our API domain, allowing you to use your existing client libraries without rewriting core logic.
This approach leverages the official SDKs for simplicity. By updating the base_url configuration, your application connects directly to https://api.playmk77.com/v1, treating our service as a drop-in replacement for the standard speech endpoint.
Base URL Change
To switch to MindVoice, update your SDK’s base URL to https://api.playmk77.com/v1. This single change routes all requests to our infrastructure while maintaining the expected JSON structure.
Your existing API key format remains compatible. Simply ensure your authorization header uses the tts-... prefix provided in your account dashboard.
- Update base_url to https://api.playmk77.com/v1
- Use standard Bearer token authentication
- No schema changes required
SDK Compatibility
The API supports the same request shape as the OpenAI speech endpoint. Official OpenAI SDKs work seamlessly with minimal configuration adjustments.
This compatibility ensures you can generate audio using familiar methods without learning a new client structure or data format.
Code Snippet
Here is a Python example using the OpenAI SDK to generate speech with the 'nova' voice: ```python from openai import OpenAI client = OpenAI( base_url="https://api.playmk77.com/v1", api_key="tts-your-api-key" ) audio = client.audio.speech.create( model="tts-1", voice="nova", input="Welcome to your meditation session." ) audio.stream_to_file("output.mp3") ``` This snippet demonstrates a basic request. Adjust the voice and input text as needed for your specific content.
Parameters
The API accepts two model identifiers, "tts-1" and "tts-1-hd", which use the same underlying engine and pricing tier. You select the model via the model field in your JSON payload, ensuring consistent output quality for your meditation or fitness scripts without needing to adjust other parameters.
Voice and speed settings allow you to tailor the audio's tone and pacing. Choose from eight preset voices ranging from calm narrators to energetic promoters, then adjust the playback rate to match the pacing of your guided sessions or workout routines.
Model Selection
Both "tts-1" and "tts-1-hd" utilize identical synthesis engines and cost the same rate. The distinction lies only in the output format options available for high-definition processing. For most fitness and meditation content, either model delivers clear, natural speech suitable for your audience.
Select your preferred model in the model field of your request body. Since pricing is identical, you can experiment with different models to see which best suits your specific content style without any additional cost implications.
- Use "tts-1" for standard generation.
- Use "tts-1-hd" for high-definition output options.
- Both models share the same price per character.
Voice Selection
Choose from eight distinct voices to match your content's vibe. Female voices like Luna offer soft, storytelling tones ideal for meditation, while Felix provides an energetic, promo-style delivery perfect for fitness ads. Male voices like Atlas deliver neutral, news-like clarity, and Orion offers deep, documentary-style narration.
Each voice is based on licensed recordings and carries an inaudible watermark that marks it as synthetic speech. You can specify the voice using the voice parameter, ensuring consistent branding across your audio library. All voices support the 23 supported languages, allowing for versatile global reach.
- Aria: Warm, clear narrator.
- Nova: Bright, upbeat energy.
- Luna: Soft, storytelling tone.
- Sage: Calm, instructional style.
- Felix: Energetic, promo voice.
- Milo: Friendly, conversational tone.
- Atlas: Neutral, news style.
- Orion: Deep, documentary voice.
Speed Control
Adjust the playback speed between 0.25 and 4.0 using the speed parameter. Slower speeds (0.5–0.8) work well for guided meditations, allowing listeners to relax and absorb instructions. Faster speeds (1.2–1.5) keep energy high for quick fitness routines or promotional clips.
This control lets you fine-tune the pacing without re-generating audio. Whether you need a soothing, slow voiceover for a yoga session or a brisk, energetic tone for a HIIT workout, you can achieve the right rhythm with a simple parameter change.
- Minimum speed: 0.25x
- Maximum speed: 4.0x
- Default speed: 1.0x
- Adjust via
speedparameter
Response Formats
Choose the audio format that best fits your delivery pipeline. We support MP3, WAV, Opus, FLAC, and PCM to balance file size and quality.
MP3
MP3 is the default choice for most web players and mobile apps. It offers a good balance between file size and sound quality, making it ideal for web players and mobile apps.
- Default format
- Universal compatibility
- Smaller file sizes
WAV
WAV provides uncompressed, high-fidelity audio. Use this format if you need pristine sound quality for professional editing or if your application requires lossless playback for guided sessions.
- Uncompressed audio
- High fidelity
- Editing ready
Opus/FLAC/PCM
Opus offers excellent compression for low-bandwidth environments. FLAC provides lossless compression for archival needs, while PCM delivers raw audio data for direct processing without encoding overhead.
- Opus: Efficient streaming
- FLAC: Lossless archive
- PCM: Raw data

Limits and Errors
MindVoice enforces strict rate limits to ensure consistent performance for fitness and meditation audio generation. Each API key is allowed 60 requests per minute. Before your first top-up, this limit is reduced to 10 requests per minute to manage initial load.
Requests are processed sequentially. Under heavy load, your synthesis job may wait in a queue. Understanding these constraints helps you design workflows that avoid delays during peak production times.
Rate Limits
Standard limit: 60 requests per minute per key.
Pre-top-up limit: 10 requests per minute.
Limits reset on a sliding window basis.
- Monitor your usage dashboard for real-time limits.
- Implement exponential backoff if you hit the 429 status code.
Character Limit
Each API request accepts up to 4,096 characters of input text. Spaces and punctuation count toward this limit. For longer scripts, split the text into chunks and concatenate the resulting audio files.
Splitting ensures that even lengthy meditation guides or fitness routines are processed reliably without exceeding the per-request threshold.
Error Codes
Failed synthesis requests are free. If a request fails, the charge is returned in full, so you can retry without cost.
Common errors include invalid API keys (401), malformed JSON (400), and rate limit exceeded (429). Check the response body for details on the specific issue.
Ensure your input text is within the 4,096 character limit and uses a supported language code if necessary to avoid processing errors.
- Retry failed requests immediately as they are free.
- Validate JSON structure before sending large payloads.
Voices Endpoint
The /v1/voices endpoint provides a complete list of available voices, their supported languages, and pricing details. This allows you to programmatically select the perfect tone for your meditation or fitness scripts without guessing.
You can also use /v1/models to verify the current engine versions. Both endpoints return JSON data that integrates easily into your content management workflows.
List Voices
Fetch all available voice presets with their attributes. Each voice is designed for specific tones, from calm narration to energetic promos.
The response includes the voice ID, name, gender, and supported output formats. Use this data to build dynamic dropdowns in your application.
- 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
Languages
All eight voices support 23 languages. If the language field is omitted, the API guesses the language from the text script (defaulting to English for Latin script).
For non-English texts using Latin characters, explicitly set the language parameter to ensure accurate pronunciation. Vietnamese, Thai, and Ukrainian are not supported.
Available Models
Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing.
tts-1-hd is available for high-definition processing.

Best Practices
Efficient API usage relies on understanding how your requests are processed and how the system handles interruptions. By following these best practices, you ensure your meditation or fitness audio projects remain reliable and cost-effective, even as your content library grows.
These guidelines help you avoid common pitfalls like exceeding character limits or encountering rate limits during high-volume production cycles.
Text Splitting
Split input text into chunks of 4,096 characters or fewer. Generate each chunk individually and concatenate the resulting audio files to create longer narrations. This ensures stable processing and prevents request timeouts.
- Max 4,096 characters per request
- Concatenate output files sequentially
- Preserve punctuation across splits
Error Handling
Handle failed requests gracefully. Failed synthesis charges are returned in full, so you can retry without losing balance. Implement exponential backoff for transient errors to manage the queue effectively.
Monitor the 60 requests per minute limit. If you exceed it, pause and wait for the window to reset rather than flooding the API.
- Retries are free on failure
- Respect the 60 RPM limit
- Use exponential backoff
Caching
Cache generated audio files locally or on a CDN. Since input text is not used for training, you can safely store outputs indefinitely. This reduces redundant API calls and lowers costs.
Use unique identifiers based on voice, model, speed, and text hash to manage cache keys effectively.
- Store outputs indefinitely
- Cache by voice and text hash
- Reduce redundant API calls
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Content creators blend calming breathwork with mindful movement to build authentic wellness engagement.
23 languages
Any voice speaks any of these languages.
