Frequently asked questions
What is the maximum text length?
The API accepts up to 4096 characters per request. For audioguides exceeding this limit, split your text into smaller chunks and concatenate the resulting audio files to create a seamless experience.
Do spaces count towards the limit?
Yes, spaces and punctuation count as characters. Your 4096-character limit includes every space, comma, and period in the input string, so plan your budget accordingly.
How do I split long texts?
Divide your text into segments of 4096 characters or fewer. Send each segment as a separate POST request and join the returned audio files sequentially to reconstruct the full audioguide.
What happens if I exceed the limit?
The API enforces a strict 4096-character maximum per request. If you exceed this, the request will fail, and you will not be charged for the failed attempt.
Can I use SSML for pauses?
No, our API does not support SSML. You cannot insert custom pauses or emphasis tags. Control pacing by adjusting the global speed parameter between 0.25 and 4.0.
How do I specify the language?
Pass the optional language field with an ISO code. If omitted, the engine guesses the language, defaulting to English for Latin script. Explicitly setting it ensures accurate pronunciation.
What if the text has numbers?
The engine handles numbers natively within the supported languages. Ensure you specify the correct language parameter so the TTS engine pronounces digits appropriately for the target audience.
How do I handle abbreviations?
The API does not offer custom pronunciation lexicons. Standard abbreviations like 'Mr.' or 'e.g.' are handled based on the detected language. Test specific cases to ensure correct output.
Should I remove HTML tags?
Yes, strip HTML tags before sending text to the API. The engine treats tags as characters and may read them aloud, disrupting the audioguide narrative flow.
How do I join audio files?
Concatenate the audio files returned from sequential requests. Since requests are processed sequentially, join the output files in the same order as your input text segments.
What is the best format for audioguides?
MP3 is a standard choice for general use due to its balance of quality and file size. Use WAV or FLAC for lossless quality, or Opus for efficient distribution. Note that the API does not support streaming; audio is returned as a complete file.
Can I change speed after generation?
No, speed is determined during synthesis. You can adjust the speed parameter (0.25–4.0) before generating audio, but the generated file itself is static and cannot be resampled dynamically.
How do I handle special characters?
Standard Unicode characters are supported. Ensure your input text is properly encoded (UTF-8). Special symbols are treated as text and spoken or ignored based on the language model.
What is the character count accuracy?
Billing is based on the exact character count sent, including spaces and punctuation. Failed requests are free, ensuring you only pay for successfully synthesized audio segments.
Text Cleaning
Preparing raw content for audioguides requires stripping markup before sending text to the API. Unescaped characters or broken tags can cause synthesis failures or unexpected pauses, disrupting the listener's experience in a museum or tour setting.
Remove HTML Tags
Strip all HTML elements (e.g., <b>, <i>, <div>) from your source text. The API processes plain text; remaining tags will be read aloud as literal strings or cause parsing errors.
- Use regex or DOM parsers to remove tags before API submission.
- Ensure alt text or attributes are converted to plain language if needed.
Handle Special Characters
Convert smart quotes, em-dashes, and non-breaking spaces into standard ASCII equivalents. Special symbols may trigger mispronunciations or be ignored by the engine, affecting clarity in multilingual narration.
- Replace ‘ ’ with standard quotes.
- Convert – to hyphens or spaces depending on context.
Normalize Whitespace
Collapse multiple spaces and line breaks into single spaces. Excessive whitespace can interfere with the 4096-character limit calculation and may introduce unintended pauses in the generated audio.
- Trim leading and trailing whitespace.
- Replace newlines with spaces to maintain flow.
Punctuation Rules
Punctuation directly controls the rhythm of your audioguide narration. Proper syntax ensures the TTS engine inserts natural pauses, preventing rushed delivery that confuses tourists in museum exhibits.
The API interprets standard marks consistently. Using correct punctuation eliminates the need for manual speed adjustments, maintaining a professional audio quality across all languages supported by the API.
Periods for Pauses
Use periods to signal complete thought endings. The engine inserts a distinct silence, allowing visitors to absorb information before the next point.
Avoid excessive periods in rapid-fire lists. A series of short sentences can sound robotic. Combine related items with commas for smoother flow.
- Use periods for distinct stops between key facts.
- Prefer periods over multiple commas for clearer separation.
Commas for Breath
Commas create brief pauses, simulating natural breathing. They prevent the voice from running on, which is critical for complex historical descriptions or directions.
Place commas before conjunctions and between clauses. This subtle break keeps the narration engaging without sounding disjointed or overly dramatic.
- Use commas for natural breathing points.
- Separate clauses to prevent monotony.
Ellipses for Effect
Ellipses (...) indicate trailing off or suspense. They create a gentle pause that works well for storytelling or emphasizing a lingering detail in an exhibit.
Use them sparingly. Overuse makes the narration sound hesitant. Reserve ellipses for moments where you want the visitor to reflect on the previous statement.
- Use ellipses for reflective pauses.
- Avoid overusing ellipses for standard sentences.
Splitting Logic
Splitting long descriptions ensures stable generation and avoids hitting the per-request limit. Each API call accepts a maximum of 4096 characters, including spaces and punctuation. Text exceeding this threshold must be divided into manageable chunks before being sent to the endpoint.
Proper splitting preserves the listening experience for museum visitors. We recommend breaking text at natural sentence boundaries rather than arbitrary character counts. This prevents audio files from ending mid-thought, ensuring that the final joined file sounds cohesive and professional.
4096 Character Limit
The API enforces a strict 4096-character limit per request. If your audioguide description exceeds this, you must split the input into multiple parts. Each part is processed independently, so ensure your split logic respects these boundaries to avoid truncation errors.
- Count all characters, including spaces and punctuation.
- Each request is capped at 4096 characters.
- Exceeding the limit returns an error.
Sentence Boundaries
Split text at logical breaks like periods, question marks, or exclamation points. This ensures that each audio segment forms a complete grammatical unit. When joining these segments later, the transition remains natural for the listener, avoiding awkward pauses or cut-off words.
- Split at sentence ends.
- Avoid mid-sentence breaks.
- Maintain grammatical integrity.
Joining Audio Files
Once you receive multiple audio files from your split requests, concatenate them in the correct order. The API returns audio files sequentially based on your input order. Standard audio libraries can merge these files seamlessly, creating a single continuous audioguide track for your application.
- Merge files in order.
- Use standard audio libraries.
- Create a single continuous track.
Character Counting
Character counting is the basis of billing. Every character in your input text contributes to the cost, regardless of whether it is a letter, a space, or a punctuation mark. This includes leading and trailing whitespace, as well as special characters. Ensure your input string accurately reflects the final text sent to the API to avoid unexpected charges.
Understanding what counts as a character helps you estimate costs before synthesis. Since spaces and punctuation are included, a 4096-character limit applies to the raw string length, not just visible words. This precision ensures transparent billing based on actual content processed.
Include Spaces
Spaces between words are counted as characters. When calculating the length of your text for audioguide narration, ensure you include all whitespace. This includes spaces between words, line breaks, and any indentation. Accurate counting prevents exceeding the 4096-character limit per request.
- Spaces between words count as characters
- Line breaks and indentation are included
- Trailing whitespace is counted
- Total string length determines the limit
Include Punctuation
Punctuation marks such as periods, commas, question marks, and exclamation points are included in the character count. Special characters like em dashes or ellipses also contribute to the total. This means that a sentence with heavy punctuation will consume more of your character budget than a plain text version.
- Periods, commas, and exclamation marks count
- Special characters like em dashes are included
- Ellipses consume characters
- Punctuation affects total length
Monitor Usage
Track your character consumption through the dashboard on the /get-api-key/ page. Each request’s character count is recorded, allowing you to monitor usage in real-time. This helps you stay within your budget and plan for larger audioguide projects. Failed requests do not incur charges, so you can test text lengths without risk.
- Dashboard shows real-time usage
- Character count per request is recorded
- Failed requests are free
- Plan budget based on actual consumption
Language Detection
Text preparation for audioguide narration requires precise language handling to ensure accurate pronunciation across your museum or tourism content. The API supports 23 languages, allowing you to deliver clear audio in Arabic, Chinese, English, French, German, Japanese, Spanish, and others. Proper language configuration prevents mispronunciations that detract from the visitor experience.
The engine automatically detects language from the script if you do not specify one. Latin-script text defaults to English. For non-English Latin text, you must set the language field explicitly. This ensures correct phonetic rendering for diverse museum collections and multilingual tour routes.
Script Detection
The API guesses the language from the character set. If you send Latin characters, it assumes English by default. This works well for English content but fails for other Latin-based languages like Dutch or Swedish.
To avoid errors, always provide the language parameter for non-English Latin text. This ensures the voice engine applies the correct phonetic rules for your specific audience.
- Latin script defaults to English
- Use
languagefield for non-English Latin text - Supports 23 specific languages
Explicit Language Code
Pass the ISO language code (e.g., de, fr, ja) in the request body. This overrides automatic detection and guarantees consistent pronunciation. All 8 voices can speak all 23 supported languages.
This approach is critical for tourism content where accuracy matters. It prevents the engine from misinterpreting proper nouns or technical terms common in museum exhibits.
- Use ISO codes like
en,es,zh - All voices support all 23 languages
- Overrides script-based guessing
Mixed Language Text
For content mixing languages, such as a tour guide switching between English and local dialects, you must split the text into separate requests. Each request should have its own language code.
This ensures each segment is processed with the correct phonetic rules. The API does not handle dynamic language switching within a single request, so splitting maintains audio quality and clarity.
- Split text by language segments
- Set
languageper request - Ensures accurate pronunciation
Speed Adjustment
Adjust the speed parameter (0.25–4.0) to match the listening context of your audioguide. Slower rates improve comprehension for complex historical details, while faster speeds suit casual walking tours where users prefer brevity.
Slower for Clarity
Set speed below 1.0 for dense informational content. This ensures listeners can process technical terms or historical dates without strain, particularly useful for museum exhibit labels or audio descriptions for visually impaired visitors.
- Use 0.75–0.9 for detailed historical narratives.
- Ideal for first-time visitors learning complex layouts.
Faster for Tours
Increase speed to 1.2–1.5 for sequential route instructions. Faster narration keeps pace with walking or driving, reducing the cognitive load of waiting for audio to catch up with the physical environment.
- Use 1.2–1.5 for walking directions.
- Reduces wait time between location triggers.
Consistent Pace
Maintain a uniform speed across all episodes or sections. Consistent pacing prevents listener disorientation and ensures a professional audio experience, especially when multiple voices or segments are stitched together.
- Lock speed settings for multi-part guides.
- Avoid abrupt changes between segments.
Voice Selection
Choosing the right voice ensures your audioguide narration matches the intended tone. With eight distinct presets, you can select between warm narrators, energetic promos, or deep documentary styles. Each voice provides consistent volume and clear pronunciation across multiple languages.
Match Tone to Content
Audioguides require specific vocal characteristics depending on the exhibit. Use 'sage' for instructional museum content or 'luna' for soft storytelling. For fast-paced city tours, 'felix' delivers energy, while 'atlas' provides neutral clarity for historical facts.
- 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
Test Different Voices
Since voices are based on licensed recordings, test samples early. Generate short clips using the API to verify clarity. The engine handles multilingual narration, so ensure the selected voice pronounces local terms correctly in all supported languages.
Consistency Across Episodes
Maintain brand identity by sticking to one voice for a single series. You can issue a new API key if needed, but keep the voice selection constant across all episodes to avoid jarring shifts for listeners.

Error Prevention
Reliable audioguide delivery depends on preventing synthesis errors before they reach the queue. By validating input and respecting API constraints, you avoid wasted credits and ensure consistent playback for museum visitors.
Proactive checks reduce latency and billing surprises. This section outlines the specific validation steps, limit monitoring, and failure handling required for a robust integration.
Validate Input
Ensure the input text does not exceed 4096 characters per request. Remove HTML tags and normalize whitespace to prevent parsing errors that could halt synthesis.
Check for unsupported characters or control codes that might distort audio output. Verify that the voice ID matches one of the eight available presets.
- Max 4096 characters per request
- Clean HTML and special characters
- Verify voice ID exists
- Normalize whitespace
Check Limits
Monitor your API key’s rate limit of 60 requests per minute (10 per minute before the first top-up). Exceeding this limit will delay synthesis, especially during peak museum hours.
Keep track of your character balance. Failed requests are free, but successful ones consume your credit. Ensure sufficient balance before batch processing.
Note that short phrases may take a few seconds to generate, so account for queue wait times in your application logic.
- 60 requests per minute limit
- Monitor character balance
- Account for queue delays
- No minimum spend required
Handle Failures
Implement retry logic with exponential backoff for transient errors. If synthesis fails, the charge is returned in full, so retries are safe.
Log request metadata including time, characters, and status for debugging. Use these logs to identify patterns in failures, such as specific voice or format issues.
Notify users or update the interface if a specific audio file fails to generate, ensuring the audioguide experience remains uninterrupted.
- Retry with exponential backoff
- Log request metadata
- Free retries on failure
- Update UI on failure
Quality Assurance
Quality assurance ensures your audioguide narration meets professional standards before deployment. By listening to samples and verifying pronunciation, you catch errors that automated checks might miss, ensuring consistent volume and clarity across all exhibits.
This process minimizes listener fatigue and maintains engagement, which is critical for tourism content where audio quality directly impacts the user experience.
Listen to Samples
Generate short audio clips using different voices like Aria or Felix to evaluate tone and clarity. Listen for natural pacing and ensure the audio matches the intended mood of the exhibit.
Use the speed parameter (0.25–4.0) to adjust playback rate and verify that the narration remains clear at your chosen speed. Test edge cases with special characters or numbers.
- Test 2–3 voices per project to find the best fit.
- Verify audio clarity at different playback speeds.
- Check for consistent volume levels across samples.
Check Pronunciation
Review the generated audio for correct pronunciation of proper nouns, street names, or technical terms specific to your location. Since the API does not support custom pronunciation lexicons, you may need to phonetically spell difficult words in the input text.
Ensure mixed-language text is handled correctly by explicitly setting the language code, preventing default English guesses for Latin-script text.
- Phonetically spell difficult proper nouns if needed.
- Explicitly set
languagefor mixed-language text. - Verify correct handling of numbers and symbols.
Review Audio Files
Download the generated audio files and inspect them for artifacts, clipping, or unexpected silences. Check that the format (mp3, wav, opus, flac, pcm) matches your delivery requirements.
Verify that the audio length aligns with your expectations based on the character count and speed settings. Ensure no metadata or watermark issues affect playback in your intended environment.
- Inspect files for audio artifacts or clipping.
- Verify format compatibility with your playback devices.
- Check audio length against expected duration.
Batch Processing
Batch processing allows product teams to generate multiple audioguide segments efficiently by queuing requests rather than waiting for each synthesis to complete individually. Since requests are processed sequentially, sending multiple inputs at once ensures a steady pipeline without overwhelming the rate limit of 60 requests per minute.
This approach is ideal for pre-generating entire tour routes or museum exhibit collections before deployment. By managing concurrency, teams can maintain consistent pacing across all audio files while staying within the single-key quota.
Queue Requests
Submit multiple text inputs to the POST /v1/audio/speech endpoint. The API processes them one after another, respecting the 60 requests per minute limit.
Ensure each text segment is under 4096 characters to avoid splitting logic complications during batch execution.
- Use parallel HTTP clients to queue requests up to the rate limit
- Keep each segment under 4096 characters to simplify joining logic
Manage Concurrency
Since requests are processed sequentially, high-volume batches may take time. Monitor your key’s usage to avoid hitting the 60 req/min cap.
For large tours, split batches into smaller chunks to maintain steady throughput without queue backlogs.
- Monitor rate limits to avoid throttling
- Split large tours into manageable batches
Track Progress
Track each request’s status to ensure all audio files are generated before assembling the final tour. Failed requests are free, so retry them immediately.
Store generated files with metadata (segment ID, duration) for easy assembly into the final audioguide sequence.
- Retry failed requests instantly
- Store audio files with segment metadata for assembly
Format Selection
Choosing the correct audio format ensures your audioguide files are optimized for delivery, editing, and storage. The API supports MP3, WAV, Opus, FLAC, and PCM, allowing you to balance quality, file size, and compatibility based on your specific workflow needs.
Selecting the right format impacts both the user experience and your infrastructure costs. By aligning your output format with your distribution channel, you maintain consistent audio quality while minimizing bandwidth usage and storage requirements for large-scale museum or tourism deployments.
MP3 for Mobile
MP3 is the standard for mobile apps and web players due to its broad compatibility and small file size. It offers sufficient quality for speech narration while reducing data usage for end-users on cellular networks.
Use MP3 when delivering final audio files directly to visitors. Its universal support ensures playback across all major iOS and Android devices without additional codec dependencies.
- Ideal for mobile app delivery
- Small file size reduces bandwidth costs
- Universal playback support
WAV for Editing
WAV provides uncompressed, lossless audio, preserving the full fidelity of the generated speech. This format is essential when your production team needs to edit, mix, or apply effects to the TTS output before final distribution.
Use WAV when integrating audio into larger multimedia projects or when high-quality master files are required for archival purposes.
- Uncompressed, lossless quality
- Ideal for post-production editing
- Larger file size than MP3
Opus for Efficiency
Opus is a supported format for efficient distribution. Note that our API does not provide streaming or WebSocket support; Opus files are generated and returned as complete files.
Use Opus when optimizing for bandwidth efficiency without sacrificing perceptible audio quality, particularly for large libraries of audioguide content.
- High quality at low bitrates
- Efficient for streaming
- Modern web support
Storage Strategy
Our API returns generated audio directly in the response without storing it on our servers. This design ensures that input text is used solely for synthesis and not retained for training. You are responsible for capturing the audio payload immediately after receiving the HTTP response to avoid data loss.
Since we do not provide a persistent storage layer, your infrastructure must handle the lifecycle of the generated files. Effective storage strategies depend on your specific use case, whether you need temporary caching for live tours or long-term archiving for museum exhibits.
Temporary Storage
Use short-lived storage for dynamic audioguides where content updates frequently. Cache generated audio in memory or ephemeral storage (e.g., Redis, in-memory stores) to serve rapid requests during active tours. This reduces latency by avoiding re-synthesis for identical text segments.
For real-time applications, store temporary files in a high-speed SSD volume with a short TTL. Note that the API does not support real-time streaming; audio is generated and returned as a complete file. Ensure your application logic handles cases where the cache expires before the user finishes listening, triggering a regeneration if necessary.
- Best for: Live tours, interactive kiosks
Permanent Archive
Persist final audio files to durable object storage (e.g., AWS S3, Google Cloud Storage) for museum exhibits and recorded tours. This ensures consistent playback quality and allows for version control of audio content.
Maintain a database mapping audio file URLs to specific exhibit IDs or text versions. This enables easy retrieval and updates without re-processing the entire text, ensuring historical accuracy for archival content.
- Best for: Museums, recorded tours
CDN Delivery
Serve archived audio via a Content Delivery Network (CDN) to reduce latency for global users. CDNs cache audio files at edge locations, ensuring fast start times for listeners in different geographic regions.
Configure cache headers (e.g., Cache-Control) appropriately to balance freshness and performance. For static exhibits, long TTLs are suitable; for frequently updated content, use shorter TTLs or cache-busting strategies.
- Best for: Global audiences, low latency
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Selecting the right voice is critical for museum audioguides, where clarity and tone must match the exhibit's context.
23 languages
Any voice speaks any of these languages.
