Frequently asked questions
What is the best voice for a museum tour?
Q: Which voice is best for a museum tour? A: Atlas offers a neutral, news-style tone ideal for factual exhibits, while Luna provides a soft, storytelling voice for immersive narratives. Sage suits instructional guides, and Milo works well for friendly, conversational explanations. Choose based on whether you prioritize neutrality or engagement for your specific content. There is no single "best" voice; select the preset that matches your script’s tone.
How do I split a long text for audio?
Split your text into parts of up to 4096 characters per request. Generate each segment individually and then join the resulting audio files. This ensures each request stays within the character limit while maintaining continuous audio playback for your museum guide.
Can I use the API for offline audio guides?
Yes. The API returns standard audio files (MP3, WAV, etc.) that you can download and store locally. Once downloaded, these files play offline on any device without requiring an internet connection or ongoing API calls during the tour.
How do I handle pronunciation errors?
The API does not support custom pronunciation lexicons or SSML. To fix errors, manually edit the input text using phonetic spelling or common abbreviations before sending it to the TTS engine. Test the output and adjust the text until the pronunciation is correct.
What is the difference between MP3 and WAV?
MP3 is a compressed format, resulting in smaller file sizes suitable for web delivery and mobile apps. WAV is uncompressed, offering higher quality but larger files. Choose MP3 for efficiency or WAV if you need lossless audio for professional archival purposes.
Can I change the speed of the audio?
Yes, you can adjust the playback speed between 0.25 and 4.0 using the speed parameter in your API request. This allows you to speed up instructional content or slow down complex explanations to match your audience's listening preferences.
Do I need to pay for every tour segment?
You pay based on character count ($0.01 per 1,000 characters). Each request counts toward your balance. Failed requests are free. Splitting a long tour into multiple segments increases the total character count slightly due to separate processing, but you only pay for what is generated.
How do I integrate audio into a mobile app?
Call the API endpoint to generate an audio file, then download the returned file. Store it locally or stream it from your server. Since the API returns standard formats like MP3 or WAV, you can play them using any standard audio player in your app.
Is the API suitable for real-time tours?
It is not designed for real-time streaming. Requests are processed sequentially, and generation takes time roughly proportional to text length (25 characters per second). For live tours, pre-generate audio files in advance and play them from storage to ensure smooth playback without latency.
Can I use my own voice for the guide?
No, custom voice cloning is not offered. You must choose from the eight available presets (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion). These voices are based on licensed recordings and cannot be customized or replaced with your personal voice.
How do I manage multiple languages?
Specify the ISO language code in the language field of your request. The API supports 23 languages, and any voice can speak any supported language. If omitted, the system guesses the language, but setting it explicitly ensures accuracy for non-English texts.
What is the character limit for a single request?
The maximum input length is 4096 characters per request. If your script exceeds this limit, split it into smaller chunks. Each chunk generates a separate audio file that you can concatenate later to create a continuous audio guide.
Do I need a developer to use this?
No coding experience is required for basic use. You can paste text into the dashboard or use the provided curl example. However, integrating the API into apps or automating workflows typically requires basic programming skills to handle requests and manage audio files.
How long does it take to generate audio?
Generation takes roughly real-time speed (25 characters per second) for long texts. Short phrases may take a few seconds. Under load, requests may wait in a queue, so processing time can vary. Plan for slight delays during high traffic periods.
Prepare Your Tour Script
Start by drafting your museum script with clear, concise sentences. Use simple vocabulary that is easy for visitors to follow while walking. Avoid complex sentence structures that might confuse the synthetic voice or sound unnatural when spoken aloud.
Write clear and concise text
Focus on short, direct statements. Keep sentences under 20 words where possible to maintain clarity for the listener.
- Use active voice for engaging narration
- Avoid jargon unless defined in audio
- Break long thoughts into separate sentences
Remove complex formatting
Strip out HTML tags, bolding, or italics before pasting text into the API. The engine reads plain text only. Special characters like em-dashes or ellipses should be written as standard hyphens or periods.
- Convert all text to plain UTF-8
- Replace symbols with words (e.g., '&' becomes 'and')
- Remove bullet points and numbering
Check character count limits
Each API request supports up to 4096 characters, including spaces and punctuation. Plan your script segments to stay within this limit. This ensures every request generates audio without truncation or errors.
- Count characters before sending
- Include spaces in your count
- Split text if it exceeds 4096 chars
Choose the Right Voice
Selecting the right voice ensures your museum audio guide matches the exhibit's atmosphere. Our eight presets range from warm narrators to energetic presenters, allowing you to tailor the experience to your specific content without needing voice actors.
Select a calm voice for history
For historical exhibits, use "sage" for a calm, instructional tone or "orion" for a deep, documentary style. These voices convey authority and clarity, helping visitors focus on the narrative details of the past.
Use friendly tones for interactive exhibits
Interactive displays benefit from engaging voices like "nova" (bright and upbeat) or "milo" (friendly and conversational).
- Use "nova" for upbeat, short instructions.
- Use "milo" for conversational, guided tours.
Match voice to target audience
Consider your primary visitors. For family-friendly attractions, "aria" offers a warm, clear narrator style that appeals to all ages. For specialized academic tours, "atlas" provides a neutral, news-like delivery that emphasizes precision over emotion.
Split Long Scripts
Tour scripts often exceed the 4,096-character limit per API request. You must divide your text into smaller segments before sending them to the endpoint.
Each segment generates a separate audio file. You will need to combine these files sequentially to create a seamless audio guide for visitors.
Divide text into 4096 character segments
Split your script into chunks of up to 4,096 characters. Spaces and punctuation count toward this limit. Ensure each segment is a complete sentence or thought to avoid awkward pauses.
- Count characters including spaces and punctuation.
- Break at natural sentence boundaries.
- Keep segments under 4,096 characters.
Generate audio for each segment
Send each segment to the API using the tts-1 or tts-1-hd model. The API returns an audio file for each request. Process requests sequentially to manage the 60 requests per minute rate limit.
Short phrases may take a few seconds, while longer texts process at roughly real-time speed. Under load, requests may queue, so plan for slight delays.
- Use
POST /v1/audio/speechfor each segment. - Monitor rate limits (60 req/min).
- Store each audio response immediately.
Combine files for the full tour
After receiving all audio files, join them in order. This creates a continuous audio guide. Use a simple audio library or script to concatenate the files.
Ensure consistent audio formats (e.g., MP3 or WAV) across all segments for smooth playback on museum devices.
- Concatenate files in the original script order.
- Use consistent formats like MP3 or WAV.
- Test the combined file for gaps or glitches.
Test with the Free Trial
Start with a zero-risk test. Sign up via Google on /get-api-key/ to receive $0.50 credit (approx. 50,000 characters). This allows you to validate audio quality without immediate payment commitment.
Generate a short script snippet using a calm voice like Luna. Download the result to verify clarity and pacing before scaling to full exhibits.
Sign up with Google for credit
Visit /get-api-key/ and authenticate with your Google account. You instantly receive $0.50 in trial credit, valid for 7 days. This provides about 50,000 characters of generation capacity, sufficient for testing multiple short audio guide segments.
- No credit card required for signup
- Credit expires after 7 days
- Instant access to API endpoints
Generate a sample audio clip
Use your new API key to send a POST request to the speech endpoint. Paste a concise museum label (under 4096 characters) and select a voice like Luna for storytelling or Atlas for neutral narration. Request the audio in MP3 format for broad device compatibility.
The system processes the request, typically returning the file within seconds for short texts. Save the returned audio file to your local machine for immediate playback testing.
Check audio quality and tone
Play the generated audio on a standard speaker or tablet to assess clarity. Verify that the voice tone matches the exhibit’s atmosphere—e.g., warm for historical narratives. Ensure no background noise or artifacts are present in the synthetic speech.
Integrate into Your App
Integrate the TTS API into your museum application by sending text to the speech endpoint. This allows you to generate audio guides directly from your scripts.
The API accepts standard JSON bodies, making it compatible with common web frameworks. You can easily embed the generated audio files into your mobile app or web interface for seamless visitor experiences.
Use the API endpoint in your code
Send a POST request to https://api.playmcww.com/v1/audio/speech with your text and voice selection. The API returns the audio file directly, which you can then store or play immediately.
You can use the official OpenAI SDK by pointing it to our base URL, or use plain HTTP requests. This flexibility ensures compatibility with most programming environments.
- Endpoint:
POST https://api.playmcww.com/v1/audio/speech - Format: JSON body with
model,input,voice,response_format - Auth:
Authorization: Bearer tts-...
Handle audio playback in your UI
Display the generated audio using standard HTML5 audio players or native mobile components. Ensure the interface allows visitors to pause, rewind, or skip to the next exhibit.
Optimize the user experience by preloading audio segments where possible, especially for interactive kiosks where network latency might occur.
- Use HTML5
<audio>or native players - Support pause, play, and skip functions
- Preload segments for smoother playback
Manage user sessions and keys
Store your API key securely in your application configuration. You can issue a new key at any time if needed, which immediately invalidates the old one.
Track character usage to stay within your budget. The API provides clear metrics on characters consumed, helping you manage costs effectively.
- Securely store API key
- Issue new keys if needed
- Monitor character usage for budgeting
Deploy to Museum Devices
Once your audio clips are generated, select MP3 or WAV formats for broad compatibility. MP3 offers smaller file sizes for efficient storage, while WAV provides uncompressed quality ideal for high-fidelity kiosks.
Download MP3 or WAV files
Retrieve the generated audio files directly from your API response or dashboard. Choose MP3 for balanced quality and size, or WAV for lossless clarity depending on your device’s storage constraints.
- MP3: Suitable for saving storage space on tablets.
- WAV: Ideal for high-end audio kiosks.
Load onto kiosks or tablets
Transfer the audio files to your museum devices via USB, Wi-Fi, or your content management system. Ensure the file structure matches your app’s expected directory paths for seamless playback.
Test on actual hardware
Play the audio on the actual tablets or kiosks to verify volume levels, speaker clarity, and touch responsiveness. Confirm that the audio guides trigger correctly at exhibit stations without lag.
Monitor Usage and Costs
Track character consumption to manage your budget effectively. The API charges $0.01 per 1,000 characters, so knowing your text length helps predict costs. Failed requests are free, ensuring you only pay for successful audio generation. Monitor your account dashboard for usage stats.
Track character consumption
Use the API dashboard to view your current balance and characters used. Since each request allows up to 4,096 characters, splitting long scripts helps you estimate expenses accurately. Remember that spaces and punctuation count as characters.
Set budget alerts
Keep an eye on your usage to avoid unexpected charges. Although there are no monthly plans, monitoring your balance ensures you can top up before running out of credit. The system provides clear data on your consumption history.
Top up as needed
Add funds using USDT on the TRON network (TRC-20). Transfers are credited automatically within minutes, with a minimum top-up of $5. Your balance never expires, allowing you to manage costs flexibly without subscriptions or invoices.
- Minimum top-up: $5
- Payment method: USDT (TRC-20)
- Credit time: Within minutes

Handle Common Issues
Even with clear scripts, TTS may mispronounce proper nouns or exhibit-specific terms. Since phoneme dictionaries are not supported, you can mitigate this by spelling out words as they should sound (e.g., "Eiffel Tower" as "Ay-Fell Tower").
Fix pronunciation errors
Use phonetic spelling for unique names or acronyms within your text input. This simple workaround ensures the voice pronounces museum-specific terms correctly without needing custom lexicons.
Adjust speed settings
If the audio feels too rushed or monotone, adjust the speed parameter between 0.25 and 4.0. Slowing down the rate (e.g., 0.9) often improves clarity for complex historical narratives.
Regenerate failed audio
Failed requests are free, so if synthesis errors occur, retry the generation. Check your character count stays under 4096 per request to avoid truncation issues.
Optimize for Multiple Languages
Museum visitors expect clear audio regardless of their native tongue. Our API supports 23 languages, allowing you to offer localized guides without hiring separate voice actors. By explicitly setting the language parameter, you ensure accurate pronunciation for non-English texts, especially those using Latin scripts that might otherwise default to English.
This precision prevents awkward phrasing and ensures your historical narratives sound natural. Whether guiding guests through ancient ruins or modern art, consistent language handling enhances the visitor experience across diverse international crowds.
Set language code for non-English
Always specify the ISO language code in your API request. Without it, the system guesses the language, which often defaults to English for Latin text. Explicitly setting codes like fr, de, or es guarantees the correct accent and pronunciation for your target audience.
This is crucial for tourist-heavy locations where visitors speak many different languages. It ensures your audio guide remains accessible and understandable to everyone.
- Use ISO codes like
ja,zh, orarfor precise control. - Default language is English for Latin scripts if not specified.
Test voice clarity in target languages
Before deploying, generate sample clips in each target language. Check that the voice sounds natural and that historical terms are pronounced correctly. Our 8 voices adapt well across languages, but testing ensures the specific tone matches your exhibit’s mood.
For example, sage works well for instructional history, while nova suits interactive exhibits. Verify clarity by listening on typical museum speakers or tablets.
- Generate samples for each language you plan to offer.
- Test on actual kiosk hardware to check speaker clarity.
Manage voice consistency across languages
Maintain a consistent brand voice by using the same preset (e.g., atlas for news-style facts) across all languages. This creates a familiar auditory experience for visitors moving between exhibits or language versions.
If a visitor switches from English to Spanish, the voice should remain recognizable. Consistency builds trust and makes the audio guide feel like a unified tour rather than disjointed clips.
- Use the same voice preset for all language versions of an exhibit.
- Ensure tone matches the exhibit’s educational level.
Maintain Your Audio Library
As exhibits evolve, your audio guides must keep pace. When a label changes or a new artifact is added, update the source script to reflect the new information. This ensures your library remains accurate and relevant for visitors.
Regenerate only the affected audio clips rather than reprocessing the entire tour. This saves time and character credits. By isolating changes, you maintain the consistency of the remaining content while updating only what has shifted.
Update scripts as exhibits change
Review your tour scripts regularly, especially for rotating exhibitions. Ensure the text matches the physical signage exactly. Clear, concise text reduces generation errors and keeps the narrative flow natural for the listener.
Regenerate affected audio clips
When a script segment changes, send the new text to the API to create an updated audio file. Since the API processes requests sequentially, batch these updates during off-peak hours if volume is high. This minimizes wait times.
Replace the old audio file in your deployment package with the new one. Ensure the new file maintains the same format (e.g., MP3 or WAV) and voice settings to preserve a seamless listening experience.
Keep version control of audio files
Store your audio files with clear version identifiers, such as including the generation date or script hash in the filename. This helps you track which audio corresponds to which script version. It is crucial for debugging if a visitor reports an error.
Maintain a simple inventory list or database linking each audio file to its source script and exhibit location. This makes it easy to locate and replace specific clips without losing the entire tour structure.
Scale for Large Collections
Creating audio guides for large museum collections requires a systematic approach to handle hundreds of exhibits efficiently. By automating the generation process, you can ensure consistent quality across all tours without manually processing each script. This method saves significant time compared to individual requests, allowing curators to focus on content rather than technical details.
Batch processing allows you to generate audio for multiple exhibits simultaneously. You can prepare a list of scripts and submit them in bulk, reducing the administrative overhead. This workflow is particularly useful for museums with extensive permanent collections that require regular updates or expansions.
Automate generation for many exhibits
Use the API to generate audio for numerous exhibits in parallel. This reduces the time needed to produce a full tour library. Automation ensures that every script is processed with the same settings, maintaining consistency in voice and quality across all exhibits.
Set up a simple script to loop through your text files and send them to the API. This method is ideal for museums with large, static collections that do not change frequently.
- Use the API endpoint to generate audio for multiple exhibits in parallel.
- Ensure consistent voice quality across all exhibits by using the same settings.
- Reduce manual effort by automating the request submission process.
Use scripts to batch process
Prepare your text files in a structured format, such as JSON or CSV. This allows you to easily manage and update scripts for multiple exhibits. Batch processing helps you keep track of which audio files have been generated and which are still pending.
You can use simple scripts to read your text files and send them to the API. This method is efficient for handling large volumes of text without overwhelming the system.
- Prepare text files in a structured format like JSON or CSV.
- Use simple scripts to read text files and send them to the API.
- Keep track of generated audio files to avoid duplication.
Manage multiple API keys if needed
If your museum has multiple departments or distinct audio guide systems, you may need more than one API key. This allows you to separate usage and track costs for different sections of the museum.
Each key has its own rate limit of 60 requests per minute. By using multiple keys, you can increase the total number of requests you can process simultaneously.
You can issue a new key at any time, and the old one will stop working immediately. This ensures that you can manage access and usage effectively across different parts of your museum.
Note that you can only have one active key per account. If you need to use multiple keys, you will need to manage them carefully to avoid conflicts.
- Use multiple keys to separate usage and track costs for different sections.
- Increase the total number of requests by using multiple keys.
- Issue a new key at any time to manage access and usage.
Support User Feedback
Visitor feedback is the most direct way to improve the quality of your museum audio guides. By listening to how visitors react to specific clips, you can identify sections that feel rushed, unclear, or disengaging. This real-world data helps you prioritize which scripts need the most attention before they become permanent fixtures in your collection.
You do not need complex analytics tools to start. Simple observation and direct comments from visitors provide immediate insights into the user experience, allowing you to make informed decisions about tone, pacing, and content clarity.
Collect visitor audio comments
Encourage visitors to share their thoughts through simple channels like comment cards, QR codes on display labels, or a dedicated email address. Ask specific questions about whether the narration was clear, engaging, and easy to follow. This direct input helps you understand the listener's perspective without needing technical infrastructure.
- Use comment cards near exhibits
- Add QR codes linking to a feedback form
- Collect email responses from visitor logs
Identify confusing sections
Look for patterns in feedback where visitors mention difficulty understanding the narration. This might indicate that the text is too dense, the voice speed is inappropriate, or the chosen voice does not match the tone of the exhibit. Note which specific clips receive the most questions or complaints.
- Note repeated questions about specific clips
- Track which voices are perceived as unclear
- Identify sections with high confusion rates
Refine scripts based on feedback
Once you identify problematic sections, edit the text for clarity and simplicity. Adjust the speed parameter in the API to ensure the narration is comfortable for the target audience. Regenerate the audio clip using the updated script and voice settings to create a smoother listening experience for future visitors.
- Simplify complex sentences
- Adjust speed settings (0.25–4.0)
- Regenerate affected audio clips
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This feedback loop ensures your final audio guide meets visitor expectations without unnecessary rework.
23 languages
Any voice speaks any of these languages.
