Frequently asked questions
What is the base URL for the API?
The base URL is https://api.playbdkk.com/v1. You can use the official OpenAI SDKs by setting base_url to this address and providing your API key. All requests are sent via POST to /v1/audio/speech for speech synthesis, while GET /v1/voices and GET /v1/models provide metadata about available voices and models.
Does the API support SSML?
No, the API does not support SSML. It accepts plain text input up to 4096 characters. You cannot use SSML tags for pronunciation or pauses. If you need precise control, you must split your text into smaller parts or adjust the speed parameter to manage pacing between sentences.
How do I change the voice language?
Set the optional language field in your request body to an ISO code, such as 'es' for Spanish or 'fr' for French. If omitted, the system guesses the language from the script, defaulting to English for Latin text. You can use any of the 8 voices for any of the 23 supported languages.
What is the character limit per request?
Each request supports a maximum of 4096 characters in the input field. Spaces and punctuation count toward this limit. For longer scripts, you must split the text into parts of up to 4096 characters, generate audio for each part, and then join the resulting audio files.
Can I stream audio in real-time?
No, the API does not support streaming or WebSocket connections. You send a text payload and receive the complete audio file in the response. Audio is generated synchronously, so you wait for the full file to be ready before receiving it. There are no real-time partial audio streams.
How do I handle long tour scripts?
Split your script into chunks of up to 4096 characters. Send each chunk as a separate request to the speech endpoint. Once you receive the audio files for each part, join them sequentially to create the final audioguide. This ensures you stay within the single-request character limit.
Is the API compatible with Python?
Yes, it is compatible with Python if you use the official OpenAI SDK. You simply configure the SDK with base_url=https://api.playbdkk.com/v1 and your API key. You can also use plain HTTP libraries like requests to send POST requests to the /v1/audio/speech endpoint with your JSON payload.
What happens if the API is slow?
Requests are processed one after another, so under load a request may wait in a queue. Typical speed is roughly real time, but short phrases take a few seconds. If the queue is long, generation time increases. Failed requests are free, but successful ones are charged regardless of speed.
Do I need to specify a model?
No, specifying a model is optional. Both 'tts-1' and 'tts-1-hd' use the same engine and price, so omitting the field or choosing either value works. Since the engine is identical, we recommend testing both variants to ensure the output meets your specific audioguide standards.
How do I rotate my API key?
You can issue a new API key at any time from your account dashboard. When you generate a new key, the old one stops working immediately. This ensures that only your current key is active. You can rotate keys as often as needed without any downtime or additional fees.
What formats are best for mobile?
MP3 is a reliable choice for mobile audioguides due to its small file size and wide compatibility. You can also select WAV, FLAC, OPUS, or PCM. MP3 offers a practical balance between quality and bandwidth usage. Choose the format that fits your app’s playback capabilities and storage requirements.
Are there SDKs for other languages?
We don’t have a proprietary SDK. Instead, use the official OpenAI SDKs for your preferred language. Just update the base_url to https://api.playbdkk.com/v1 and supply your API key. This works for Python, Node.js, Java, Go, and other languages supported by the OpenAI SDK.
How do I check my usage?
Log in to your account at /get-api-key/ to view your balance, characters left, and usage history. The dashboard displays your current balance, trial status, and character consumption. Request metadata, including time, characters, and status, is kept for billing purposes and is visible in your account details.
Is the API synchronous or asynchronous?
The API is synchronous. You send a request and receive the complete audio file directly in the response. There is no webhook or callback mechanism for completion. You must handle the waiting time in your application logic while the server processes the text. For long texts, split them into parts of up to 4096 characters and join the resulting audio files.
First request
curl
curl https://api.playbdkk.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.playbdkk.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.playbdkk.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 |
Get Your API Key
Sign up for an account on the /get-api-key/ dashboard using your Google account or email. This creates your unique workspace where you can manage credentials and monitor usage specifically for your museum or tourism projects.
Sign up on the dashboard
Create an account on the /get-api-key/ page using Google or an email and password combination. Google sign-ins receive a $0.50 trial credit valid for 7 days, equivalent to about 50,000 characters. Email-based accounts start without trial credit.
Copy your Bearer token
Once registered, your dashboard displays your active Bearer token. Use this key in the Authorization: Bearer <key> header for all API requests. Each account maintains one active key at a time.
Rotate keys if needed
You can issue a new key at any time from the dashboard. The previous key stops working immediately, ensuring secure access control for your team without needing to wait for expiration.
First Request with cURL
Generate audio by sending a POST request to the speech endpoint. The API returns the complete audio file in the response body, not as a stream.
This approach ensures you receive a single, unified file ready for download or immediate playback in your museum application.
Basic speech generation
Send a POST request to https://api.playbdkk.com/v1/audio/speech with your text and voice selection. The request must include a valid Bearer token in the Authorization header.
- Endpoint:
POST https://api.playbdkk.com/v1/audio/speech - Header:
Authorization: Bearer tts-... - Body: JSON with
model,input, andvoice
Setting voice and format
Choose from 8 voice presets like aria or atlas and specify the language if needed. The API supports MP3, WAV, OPUS, FLAC, and PCM formats.
- Voice: e.g.,
aria,nova,atlas - Format:
mp3,wav,opus,flac, orpcm - Language: optional ISO code (defaults to English for Latin script)
Handling the response
The response body contains the binary audio data. Save this directly to a file or pass it to your player. Failed requests return an error JSON instead of audio.

Using the OpenAI SDK
To use MuseVoice with the OpenAI SDK, install the official library via pip. The SDK simplifies HTTP requests by handling JSON serialization and authentication headers automatically, allowing your code to focus on logic rather than network details.
Configure the client to point to our API base URL. This ensures all standard methods like audio.speech route correctly to our infrastructure. The SDK treats our endpoint as a drop-in replacement for the OpenAI speech endpoint, maintaining familiar method signatures.
Install the official SDK
Run pip install openai to add the library to your project. This is the same package used for OpenAI’s services, ensuring broad compatibility and regular updates from the maintainers.
Change base URL
Set the base_url parameter in your client initialization to https://api.playbdkk.com/v1. This directs all API calls to MuseVoice’s servers while keeping the standard request structure intact.
Use standard methods
Call client.audio.speech() with your model, voice, and input text. The SDK returns the complete audio file bytes in the response body, which you can save directly to a file or stream to a player. Since we do not support streaming, the entire file is delivered at once upon completion.
- Use
response_formatto specify MP3, WAV, OPUS, or FLAC. - Pass your
Authorization: Bearerkey via the SDK client config. - Handle errors by checking the HTTP status code in the response.
Supported Parameters
Configure your synthesis requests with specific parameters to match your audioguide’s tone. The API accepts standard models and voice presets, allowing you to tailor the audio output precisely for different exhibits or tourism contexts without needing complex engineering.
Model selection (tts-1, tts-1-hd)
Use "tts-1" or "tts-1-hd" for synthesis. Both options use the same engine and price, offering identical output quality. Choose based on your preference, as there is no sonic difference between the variants.
Voice presets (8 options)
Select from eight licensed voices to suit your content. 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).
Each voice is based on licensed recordings from LibriTTS-R and LibriVox. They support all 23 languages, with language guessing based on script if not explicitly set.
Speed control (0.25–4.0)
Adjust the speed parameter between 0.25 and 4.0 to control the pacing of the audio. This allows you to slow down complex historical explanations or speed up quick transit announcements while maintaining natural intonation.
Audio Formats
MuseVoice returns audio files in four standard formats: MP3, WAV, OPUS, and FLAC. You select the format via the response_format field in your API request. The choice determines file size and compatibility, allowing you to balance storage efficiency with playback quality for your museum or tourism application.
Since the API returns complete audio files rather than streaming partial data, you should choose a format that fits your delivery constraints. MP3 is the most universally compatible choice for web players and mobile apps, while WAV offers uncompressed quality for high-fidelity playback systems.
MP3 for web and apps
MP3 is the recommended format for most tourism and museum use cases. It provides a good balance between file size and audio quality, making it ideal for downloading via HTTP and playing in standard web or mobile audio players. Its small size ensures faster transfer times for users on slower mobile networks.
Use response_format: "mp3" when generating audio for general audioguides, website content, or mobile app integration. This format is widely supported across all modern browsers and operating systems without requiring additional codecs.
- Small file size for efficient storage
- Universal compatibility with web and mobile players
- Suitable for standard HTTP delivery
WAV for high quality
WAV provides uncompressed audio, preserving the full quality of the synthetic speech. This format is ideal for professional recording studios, high-end audio installations, or archival purposes where maximum fidelity is required. The trade-off is significantly larger file sizes compared to MP3.
Select response_format: "wav" when quality is prioritized over bandwidth. WAV files are large but contain no lossy compression artifacts, ensuring the voice remains crisp and clear during playback on high-quality speakers.
- Uncompressed, lossless audio quality
- Ideal for professional archiving
- Larger file sizes than MP3
OPUS and FLAC options
OPUS is a highly efficient, lossy codec that offers better compression than MP3 at similar perceived quality. It is suitable for modern applications where bandwidth conservation is critical, such as dense audio libraries or large-scale distribution. FLAC provides lossless compression, reducing file size without sacrificing quality, making it a middle ground between WAV and MP3.
Use response_format: "opus" or response_format: "flac" depending on your specific storage and quality needs. Note that while these formats are efficient, MuseVoice delivers them as complete files, not as streaming streams.
- OPUS: High efficiency, small size
- FLAC: Lossless compression
- Complete file delivery, not streaming

Rate Limits and Queues
Rate limits protect the stability of our synthesis engine. You are allowed 60 requests per minute for each active API key. This cap ensures consistent performance for museum and tourism applications generating audioguides or audio content.
60 requests per minute
Your limit is calculated per API key. If you rotate your key, the new key starts with its own quota. Failed requests do not consume your balance but still count toward this rate limit.
10 requests before top-up
New accounts begin with a lower limit of 10 requests per minute. This applies until you complete your first top-up. Once you add funds via USDT on the TRON network, your limit increases to 60 requests per minute.
- Limit applies before the first top-up
- Increases to 60 req/min after funding
Queue processing on load
Requests are processed sequentially. Under high load, your request may wait in a queue before synthesis begins. This is normal and ensures fair resource distribution across all users.
Typical generation speed is roughly real-time for long texts, but short phrases may take a few seconds. Be patient with queue delays during peak usage.
Error Handling
Handling errors is straightforward when you understand the API’s behavior. Failed synthesis requests are free, so you can retry confidently without billing penalties. This allows you to test your integration logic without worrying about unexpected costs for transient network issues or temporary server congestion.
We recommend implementing exponential backoff for rate limit errors and simple immediate retries for other transient failures. Always check the response status code to determine if the request succeeded or if the audio generation failed due to invalid parameters or input constraints.
Common error codes
Use standard HTTP status codes to diagnose issues. A 401 Unauthorized error means your Bearer token is missing or invalid. A 400 Bad Request indicates malformed JSON or unsupported parameters. If you exceed the limit, you receive a 429 Too Many Requests response.
Note that failed synthesis attempts do not consume your character balance. This means you can retry a failed request multiple times without affecting your paid usage, provided you stay within the rate limits.
- 400 Bad Request: Check your JSON structure and voice IDs.
- 401 Unauthorized: Verify your Authorization header.
- 429 Too Many Requests: Wait before retrying.
Retry logic
For 429 errors, implement a retry with exponential backoff. Start with a short delay and increase it for each subsequent attempt. This prevents overwhelming the API when it is under load. For 500-series errors, a simple immediate retry is often sufficient since failed requests are free.
Keep track of your retry attempts to avoid infinite loops. If a request fails after several retries, log the error details and pause further attempts until the next minute begins.
Character limit errors
Each request supports up to 4096 characters. If your input text exceeds this limit, the API will return an error. You must split your text into smaller chunks before sending them. This ensures that each request stays within the allowed size constraint.
Split your text into parts of up to 4096 characters and join the audio files after generation. This approach allows you to generate audioguides or long-form content without hitting the single-request limit.

Long Text Handling
Audioguide scripts often exceed the 4096-character limit per request. You must split your text into smaller chunks and send them sequentially to generate individual audio files.
Split text into 4096 chars
Break your script into segments of up to 4096 characters. Each segment becomes a separate API call. This ensures every part of your narration is processed within the system's constraints.
Join audio files
Receive multiple audio files from your requests. Concatenate them in your application to create a continuous audioguide experience for tourists. The API returns standard formats compatible with most media players.
Manage synthesis time
Processing takes roughly real-time speed (25 characters per second). Under load, requests queue and wait. Plan your generation window accordingly, especially for large museum collections with many long scripts.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Our audioguide transforms museum visits into immersive storytelling experiences for visitors.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- Python documentation
- IETF RFC 7845: Ogg Opus
- LibriVox public-domain audiobooks
- openai-node on GitHub
- Node.js documentation
- TRON developer hub: TRC-20
- LibriTTS-R paper (arXiv 2305.18802)
- ISO 639 language codes
- W3C WAI: making audio and video accessible
- Creative Commons Attribution 4.0
- MDN: Web Speech API
