Frequently asked questions
What is the character limit per request?
Each API request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. This constraint applies to every individual call made to the /v1/audio/speech endpoint. If your script exceeds this length, you must split the content into multiple requests to ensure successful synthesis and delivery of the audio files.
Can I use the API for commercial training?
Yes. The API is designed for scalable corporate use, including HR agencies and training teams. Generated audio files are returned in the response and are not stored by the provider. Input text is used only for synthesis and not for training models, making it suitable for internal or external commercial training modules.
How do I handle long training scripts?
Split your script into parts of up to 4096 characters. Generate audio for each part via separate API calls, then join the resulting audio files. Requests are processed sequentially, so under load, a request may wait in a queue. Typical speed is roughly real-time, generating about 25 characters per second.
Which voice is best for instructional content?
Q: Which voice is suitable for instructional content? A: Sage is designed as a calm, instructional voice suitable for training modules. Luna is also suitable for soft, storytelling formats. Both are available presets. You can adjust the speed between 0.25 and 4.0 to match the pacing of your corporate training materials effectively.
Is the audio quality suitable for professional use?
The API uses licensed recordings from LibriTTS-R and LibriVox, providing clear, consistent synthetic speech. Every file includes an inaudible watermark marking it as synthetic. The voices are based on licensed data, ensuring consistent quality for scalable e-learning modules without expensive studio sessions.
Can I change the voice mid-sentence?
No. The API accepts a single voice preset per request. To change voices, you must split the text at the desired point and make separate API calls for each segment. You can then join the resulting audio files to create a seamless training module.
How does language detection work?
If the language field is omitted, the system guesses the language from the script. Latin script text defaults to English. For non-English Latin-script text, you should explicitly set the language parameter. Supported languages include Arabic, Chinese, Danish, and 20 others listed in the API documentation.
What happens if the API fails?
Failed requests are free. If synthesis fails, the charge is returned in full. This ensures you only pay for successful audio generation. You can retry the request or split the text further if the error was due to input constraints or temporary load issues.
Preparing your training text
Before generating audio, estimate your character count precisely. VocalGuide charges $0.01 per 1,000 characters, including spaces and punctuation. Accurate counting prevents unexpected costs and helps you plan your budget for large e-learning modules.
Ensure your text is clean and ready for processing. The API does not support SSML or custom pronunciation lexicons, so pauses and emphasis are determined by punctuation and cannot be explicitly controlled.
Character count estimation
Calculate the total characters in your script, as spaces and punctuation count toward the limit. This helps you estimate costs accurately before making API calls.
Use simple text editors or scripts to count characters. This ensures you stay within the 4,096-character limit per request and avoid unnecessary charges.
- Include spaces and punctuation in your count
- Estimate costs at $0.01 per 1,000 characters
- Plan for large modules by pre-counting text
Text splitting strategies
Split longer texts into segments of up to 4,096 characters. This ensures each request stays within the API limit and maintains audio quality.
Use logical breaks like sentences or paragraphs when splitting. This helps the API generate clear, coherent audio segments that are easier to join later.
- Split at sentence or paragraph boundaries
- Keep segments under 4,096 characters
- Maintain logical flow between segments
Punctuation handling
Ensure proper punctuation in your text. Commas, periods, and question marks help the API determine pauses and intonation, resulting in more natural speech.
Avoid excessive punctuation, which can lead to unnatural pauses. Clean text ensures smoother voiceover generation for your training content.
- Use standard punctuation for natural pauses
- Avoid excessive or unusual symbols
- Clean text for better audio quality
Selecting the right voice
Choosing the correct voice model ensures your corporate training modules resonate with the intended audience. The distinction between a warm narrator and a clear instructional guide directly impacts learner engagement and information retention in e-learning environments.
Narrator vs instructional
For narrative-heavy content, such as company history or soft-skills storytelling, use Aria or Luna. Their warm, clear tones are based on licensed recordings, keeping learners engaged without fatigue. Conversely, for procedural guides or compliance updates, Sage or Milo provide a calm, instructional clarity that reduces cognitive load.
- Use Aria for engaging, narrative-driven soft skills modules.
- Select Sage for clear, step-by-step technical instructions.
- Avoid high-energy voices for dense compliance text to prevent listener fatigue.
Gender and tone options
Our eight presets cover diverse tonal needs without requiring custom design. Male voices like Felix offer energetic delivery for promotional or fast-paced updates, while Atlas provides a neutral, news-style tone ideal for factual reporting. Orion’s deep, documentary style suits serious, long-form educational content.
- Felix: Energetic, suitable for promo or quick updates.
- Atlas: Neutral, ideal for news-style factual reporting.
- Orion: Deep, best for serious documentary-style content.
Consistency across modules
Maintaining a single voice across multiple training modules builds brand recognition and reduces learner disorientation. Since all voices support all 23 languages, you can ensure tonal consistency even when localizing content, provided you explicitly set the language ISO code to avoid auto-detection errors.
- Stick to one voice per curriculum series.
- Explicitly set the language code to prevent auto-detection mismatches.
- Use the same voice for related modules to aid recognition.
Configuring language settings
Setting the correct language parameter ensures accurate pronunciation, especially when Latin script text is not English. The API guesses the language if the field is omitted, defaulting to English for Latin characters, but explicit codes prevent errors in mixed-language corporate training modules.
ISO code usage
Pass the ISO 639-1 code (e.g., es, fr, de) in the request body. This guarantees the selected voice applies the correct phonetic rules for that language, regardless of the voice preset chosen. All 23 supported languages are available with every voice.
Auto-detection limits
Automatic detection works for distinct scripts but may misidentify Latin-script texts that are not English. If your training content includes German, Dutch, or Portuguese written in Latin characters, omitting the language field risks defaulting to English pronunciation, reducing clarity.
- Latin script defaults to English if
languageis unset.
Multi-language projects
For courses with mixed languages, send separate requests for each language segment. The API does not auto-switch languages within a single request. You must specify the language code for each segment to ensure consistent audio quality across your curriculum.
Processing long documents
Long training modules often exceed the 4,096-character limit per request. Splitting your source text into segments ensures every part is processed correctly without truncation.
Each segment generates a separate audio file. The API returns these files in the response order, ready for assembly into a single continuous learning module.
Segmentation rules
Break text at natural pauses, such as end-of-sentence markers or paragraph boundaries. This prevents mid-word cuts that disrupt listening flow.
Ensure each segment stays under 4,096 characters, including spaces and punctuation. This limit is strict and applies per API call.
- Split at sentence or paragraph breaks
- Stay under 4,096 characters per segment
- Avoid splitting mid-clause
Audio joining
After receiving individual audio files, concatenate them using your preferred audio tool or script. This creates a seamless playback experience for learners.
Maintain consistent formatting (e.g., MP3 or WAV) across all segments to ensure smooth joining without codec issues.
- Use consistent audio formats
- Concatenate in original order
- Verify no gaps between segments
Latency considerations
Processing is sequential. Long documents may take time, roughly matching real-time speech duration. Short phrases take a few seconds.
Under load, requests may queue. Plan your generation window accordingly to avoid delays during peak usage periods.
- Roughly real-time speed
- Requests processed sequentially
- Queue delays possible under load
Testing and quality assurance
Before integrating voiceovers into your e-learning modules, validate audio quality by generating short samples. Submit text up to 4096 characters to the API and review the output for clarity, pacing, and natural flow. This step ensures the synthetic voice meets your training standards before bulk processing.
Speed adjustments allow you to fine-tune delivery. The API accepts speeds between 0.25x and 4.0x. Slower rates improve comprehension for complex technical content, while faster rates suit routine procedural updates. Always test extreme speeds to ensure intelligibility remains high for learners.
Sample generation
Generate test clips using the tts-1 or tts-1-hd models. Verify that the selected voice, such as Sage for instructional content, maintains a consistent tone. Check that the output accurately reflects the intended emphasis and pacing without requiring manual editing.
Use the API’s standard response to download the audio file. Review the file locally to confirm there are no artifacts or unnatural pauses. This validation step prevents costly rework during large-scale curriculum production.
Speed adjustments
Adjust the speed parameter to match your audience’s learning pace. A speed of 1.0x is standard, but increasing to 1.2x or 1.5x can keep advanced learners engaged without sacrificing clarity.
Remember that requests are processed sequentially. Under load, synthesis may queue, so test speed variations under typical load conditions to ensure consistent latency for your training modules.
Format verification
Choose the response_format that best fits your Learning Management System (LMS). MP3 offers small file sizes and broad compatibility, while WAV provides uncompressed quality for high-fidelity playback.
Verify that the generated audio plays correctly in your target browsers and devices. Ensure the file format does not introduce additional overhead or compatibility issues with your existing e-learning infrastructure.
Integrating into LMS
Integrating VocalGuide’s API into your LMS streamlines the creation of scalable e-learning modules. By replacing manual studio bookings with automated synthesis, HR teams can update training content rapidly without waiting for external voice actors.
The API’s standard JSON structure ensures compatibility with most modern learning management systems. Teams can generate audio on demand, ensuring that text updates in the LMS are reflected instantly in the audio files without manual re-exporting.
API webhooks
While our API does not support streaming or webhooks, you can implement a polling mechanism or trigger synthesis via your LMS’s custom actions. This allows you to generate audio files asynchronously when a new course module is published.
Use the standard POST endpoint to initiate speech generation. Since requests are processed sequentially, batching requests for a full module ensures consistent throughput without overwhelming the queue during peak hours.
- Use POST /v1/audio/speech for batch generation
- Poll status via standard HTTP responses
- No webhooks required; use polling or custom triggers
File storage
Generated audio files are returned directly in the API response and are not stored by VocalGuide. Your LMS or cloud storage should handle persistence immediately after retrieval to ensure availability for learners.
Store files in formats compatible with your LMS, such as MP3 or WAV. Since balance does not expire, you can regenerate files for updated content without losing historical audio versions if stored properly.
- Audio is not stored by the API
- Store immediately after API response
- Use LMS-native storage for long-term access
Playback compatibility
Supported formats like MP3, WAV, Opus, FLAC, and PCM ensure broad compatibility with most LMS players. MP3 is recommended for balanced quality and file size, while WAV offers lossless audio for high-fidelity training.
Test playback across devices used by your workforce. Since audio files are standard media formats, they work seamlessly with HTML5 audio players embedded in most modern learning management systems.
- MP3, WAV, Opus, FLAC, PCM supported
- MP3 recommended for size/quality balance
- Works with standard HTML5 audio players
Managing costs at scale
Managing costs at scale requires understanding the simple pricing model: $10 per million characters, or $0.01 per 1,000 characters. Spaces and punctuation count toward this total. Failed requests are free, ensuring you only pay for successful audio generation. This model supports predictable budgeting for large training libraries without hidden fees or monthly subscriptions.
To optimize efficiency, split long documents into segments under 4,096 characters. This prevents partial failures. Since requests are processed sequentially under load, batching smaller texts does not reduce queue wait times. Always verify the final character count before sending to avoid unexpected charges from oversized payloads.
Bulk processing
Process multiple training modules simultaneously by splitting texts into 4,096-character chunks. Each chunk generates a separate audio file, which you can join later. This approach ensures that a single error in one segment does not invalidate the entire course module.
Use the standard API key for all bulk jobs. Since each request counts against your 60 requests-per-minute limit, staggering large batches can prevent throttling. Failed requests incur no charge, so retrying failed chunks is cost-effective.
- Split text at natural sentence boundaries to avoid mid-sentence audio cuts.
- Join generated audio files sequentially to create complete training modules.
- Retry failed requests immediately; they do not incur additional charges.
Rate limit optimization
The API allows 60 requests per minute per key. For large-scale training content, monitor your usage to stay within this limit. If you exceed the limit, requests may queue, increasing latency. Use a single API key to simplify tracking and avoid spreading limits across multiple accounts.
Before your first top-up, the limit is lower at 10 requests per minute. Ensure your account is funded to maintain consistent throughput during bulk generation phases. This prevents delays in delivering training materials to your LMS.
- Monitor API usage via the dashboard to avoid hitting the 60-request limit.
- Use a single key to consolidate rate limits and simplify billing.
- Stagger bulk jobs if processing thousands of modules simultaneously.
Budget tracking
Track character usage and costs through your account dashboard. The dashboard shows your current balance, characters used, and remaining trial credit. Since the pricing is linear ($0.01 per 1,000 characters), you can easily estimate costs for new training content before generating it.
No monthly plans or minimum spend means you only pay for what you use. Unused balance does not expire, allowing you to accumulate credits for future training updates. Top-ups via USDT on the TRON network are credited automatically, ensuring continuous availability.
- Check the dashboard for real-time balance and character usage.
- Estimate costs before generation: 1,000 characters cost $0.01.
- Top-ups are instant; no invoices or VAT to manage.

Handling errors and retries
Corporate training pipelines must anticipate failure. Network interruptions or API timeouts can halt bulk generation, causing delays in module deployment. Implementing exponential backoff for retries ensures that temporary network blips do not corrupt your audio assets or leave partial modules in your LMS.
Network issues
Retries should handle transient 5xx errors gracefully. Do not retry immediately; use a short delay to avoid overwhelming the server during brief outages. Since requests are processed sequentially, a queue delay might resolve itself without needing a full retry.
- Retry on 502, 503, 504 status codes.
- Use exponential backoff with jitter.
- Limit retries to 3 attempts max.
Text length errors
The API strictly enforces a 4096-character limit per request. If your training script exceeds this, the request fails immediately. You must split your text into chunks before sending, then join the resulting audio files. This prevents wasted credits on failed long-form submissions.
Voice unavailability
While all 8 voices are generally available, transient unavailability can occur during high load. Your integration should detect this and either wait or switch to a fallback voice like 'sage' for instructional content, ensuring the training module still generates without manual intervention.
Localization workflows
Localization ensures your training content resonates globally without sacrificing audio quality or consistency. By integrating translation workflows with our API, HR teams can produce compliant e-learning modules in 23 languages, leveraging automatic voice matching for each region.
Translation integration
Translate your source text into target languages, then pass the ISO language code (e.g., zh-CN, de-DE) to the API. This ensures correct pronunciation and intonation, avoiding the errors of auto-detection on Latin-script texts.
- Use explicit
languageparameters for non-English Latin texts to prevent default English detection.
Voice matching
Select voices that align with regional preferences. For example, use aria for clear narration in German or nova for upbeat Japanese content. Maintain a consistent voice across all modules in a specific language to build learner trust.
- Map specific voices to languages for consistent brand tone across global curricula.
Cultural tone checks
Review generated audio for pacing and clarity. While voices are neutral, adjusting the speed parameter (0.25–4.0) can accommodate different speech patterns. Generate short samples to verify that the synthetic tone matches your training’s instructional style.
- ['Adjust speed for optimal comprehension in slower-speaking languages.']
Audio format selection
When designing corporate training audio, the choice between MP3 and WAV balances file efficiency against production flexibility. MP3 offers high compression with minimal quality loss, making it ideal for web delivery. WAV provides uncompressed, lossless audio, suitable for high-end broadcast or further editing in production suites.
MP3 vs WAV
MP3 is the standard for web-based LMS playback, ensuring broad compatibility across devices. WAV files preserve every audio detail, which is useful if your team plans to apply additional audio effects or master the tracks before final distribution.
- MP3: Compressed, smaller files, universal web support.
- WAV: Uncompressed, larger files, high fidelity for editing.
File size implications
Audio files directly impact storage costs and download times. MP3 files are significantly smaller than WAV equivalents, reducing the burden on your LMS storage and speeding up initial load times for learners. For long training modules, this difference becomes substantial.
- MP3 files are significantly smaller than WAV files.
- Smaller files reduce bandwidth costs and storage requirements.
Bandwidth considerations
Choosing MP3 ensures smoother playback for users on slower connections, a common scenario in global corporate environments. WAV files may cause buffering delays on mobile devices or in areas with limited internet infrastructure, potentially disrupting the learning experience.
- MP3 minimizes buffering issues on varying connection speeds.
- WAV may require stable, high-bandwidth connections for smooth playback.
Voice cloning alternatives
Custom voice cloning is not offered. Our API uses eight licensed presets derived from LibriTTS-R and LibriVox recordings, ensuring consistent, high-quality synthetic speech without the variability of cloning models.
This approach eliminates the need for complex consent workflows and extensive training data, providing a reliable foundation for corporate training modules where voice consistency is paramount.
Why not cloning
We do not provide custom voice cloning for customers, nor do you upload your own voice. The eight presets—such as Aria, Nova, or Atlas—are based on licensed recordings, removing the legal and technical overhead of cloning.
Preset advantages
Presets like Felix for energetic promos or Milo for conversational training offer immediate usability. Each voice is optimized for clarity and tone, reducing the time spent on fine-tuning parameters compared to custom cloning setups.
- Eight distinct, licensed voices
- No additional training data required
- Immediate availability across 23 languages
Consistency benefits
Using a fixed set of voices ensures that all modules in your e-learning curriculum maintain a uniform auditory identity. This consistency aids learner retention and brand recognition across different training languages.
Data privacy compliance
Corporate training modules often contain sensitive employee data, procedural knowledge, or internal communications. VocalGuide ensures that the text you submit for synthesis is used strictly to generate the audio file and is not ingested into our training datasets. This isolation prevents your proprietary curriculum content from influencing future model improvements or appearing in other clients' outputs.
Employee data handling
Input text is processed in real-time to produce the audio response and is not stored long-term. Once the audio is returned to your API client, the raw text input is not retained for analysis. This ensures that personal details or internal jargon within your training scripts remain transient and secure during generation.
No training usage
Unlike some consumer-grade TTS services, VocalGuide does not use your input text for model training. Your voiceovers are generated from licensed recordings (LibriTTS-R and LibriVox) and do not incorporate your specific corporate data. This separation guarantees that your unique training content remains exclusive to your organization.
Audit trails
Request metadata, including timestamp, character count, and status, is retained solely for billing purposes. These records provide a clear audit trail for your compliance team, allowing you to track exactly which texts were processed and when. This data supports internal audits without exposing the actual content of your training modules.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. His impartial tone ensures clarity and neutrality when delivering regulatory information.
23 languages
Any voice speaks any of these languages.
