Frequently asked questions
What is a TTS API?
A cloud text-to-speech API lets you send text and receive an audio file via a POST request. It uses a standard JSON body compatible with OpenAI SDKs. You simply provide text, select a voice, and receive the generated audio file directly in your application or WordPress site without managing complex infrastructure.
How do I install TTS on WordPress?
Since there is no official WordPress plugin, you integrate via HTTP requests or a custom script. Send a POST request to https://api.melolo.cc/v1/audio/speech with your API key. You can generate audio files and embed them using standard HTML5 audio tags or a custom Gutenberg block built by your developer.
Is TTS API free?
It is not entirely free. You receive a free trial of $0.50 credit (about 50,000 characters) valid for 7 days when signing in with Google. After that, usage costs $10 per 1 million characters. Failed requests are free, but standard generation incurs charges based on character count.
Which voice is best for blogs?
Suitability depends on your blog’s tone. Aria offers a warm, clear narrator style. Luna provides a soft, storytelling voice. Sage is calm and instructional. Felix is energetic and promo-focused, while Atlas is neutral and suitable for news. All eight voices support 23 languages, allowing you to match the specific mood of your content accurately.
How much does it cost?
Pricing is $10 per 1 million characters, or $0.01 per 1,000 characters. Spaces and punctuation count as characters. There are no monthly plans, seats, or minimum spends. You pay only for what you use, topped up via USDT on the TRON network, with no expiration on your balance.
Can I use my own voice?
No. The API offers eight preset voices based on licensed recordings from LibriTTS-R and LibriVox. There is no custom voice cloning feature available for customers. You cannot upload your own voice recording to generate audio in your unique voice; you must choose from the provided male or female presets.
Does it support all languages?
It supports 23 languages including English, Spanish, German, French, Chinese, Japanese, and Hindi. It does not support Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, or Bengali. Any voice can speak any supported language. If the language is not set, it guesses from the script, defaulting to English for Latin text.
How long does generation take?
Generation is roughly real-time, processing about 25 characters of text per second. Short phrases take a few seconds, while longer texts take proportionally longer. Requests are processed sequentially, so under load, a request may wait in a queue before synthesis begins, potentially increasing total wait time.
Can I play audio directly?
Yes, the API returns an audio file (mp3, wav, opus, flac, or pcm) in the response. You can save this file to your WordPress media library or play it directly using HTML5 audio players. The generated files contain an inaudible watermark marking them as synthetic speech.
Is it SEO friendly?
Audio files themselves are not directly indexed as text by search engines, but they enhance user experience and accessibility. Using descriptive filenames and alt text for audio players helps SEO. Since input text is not stored, ensure your blog content remains robust for indexing while audio serves as a supplementary feature.
Does it work on mobile?
Yes, the generated audio files are standard formats like MP3 or WAV, which play on all mobile devices. The API is accessed via standard HTTP requests, so any mobile-responsive website or app can integrate the audio seamlessly without requiring a specific mobile SDK or native application installation.
How do I handle errors?
If synthesis fails, the request charge is returned in full. You should implement logic to check the HTTP response status. If an error occurs, retry the request or split long texts into parts under 4096 characters. Failed requests do not consume your balance, ensuring you are not charged for errors.
Can I customize the speed?
Yes, you can adjust the speed between 0.25 and 4.0 using the speed parameter in your API request. This allows you to slow down narration for clarity or speed up content for quick updates. The default speed is typically 1.0, providing natural pacing for most blog content.
What is SSML?
SSML (Speech Synthesis Markup Language) is not supported by this API. You cannot use SSML tags to control pauses, pitch, or emphasis within the audio output. You must rely on the text structure and voice selection to convey tone. There are no phoneme dictionaries or custom pronunciation lexicons available.
Understanding TTS API Basics
The API accepts plain text via a standard HTTP POST request. You send your blog content, up to 4096 characters per call, to the speech endpoint. The system processes the input synchronously, but requests are queued sequentially. Under load, a request may wait in a queue before synthesis begins, so behavior depends on server load.
Audio generation typically takes a few seconds for short phrases. For longer blog posts, split the text into chunks. The API returns the audio file directly in the response, allowing your plugin to save it locally or stream it immediately to the user's browser. Note that there is no WebSocket or streaming endpoint; the full file is returned upon completion.
Text Input Mechanism
Send text via JSON body. Include voice, model, and format. Max 4096 characters per request. Spaces count as characters.
Set the language ISO code to ensure correct pronunciation. If omitted, the API guesses from the script, defaulting to English for Latin text.
- JSON POST body
- Max 4096 characters
- Optional language code
Audio Generation Process
Requests are processed sequentially. Under load, queues may form. Typical speed is roughly real-time (25 characters per second).
Failed requests incur no charge. Ensure your plugin handles retries for temporary network issues.
- Sequential processing
- Real-time generation speed
- No charge on failure
Response Delivery
The API returns the audio file directly in the HTTP response. Supported formats include MP3, WAV, OPUS, FLAC, and PCM.
Choose MP3 for web compatibility or WAV for higher quality. The file is ready for immediate embedding in your WordPress theme.
- Direct file response
- Multiple format support
- Immediate playback ready
WordPress Integration Steps
For WordPress integration, you can build a custom plugin that handles the HTTP POST to https://api.melolo.cc/v1/audio/speech. This approach gives you full control over the request lifecycle, allowing you to store the API key securely in the database and manage the 4096-character input limit per request. The plugin should handle the JSON body, including the model, voice, and input fields, ensuring the authorization header is correctly formatted with your Bearer token.
Plugin Development
Develop a plugin that wraps the API call, handling authentication and error states. Store your API key in the WordPress options table, encrypting it if possible. The plugin should send the text payload to the endpoint and handle the response, which returns the audio file directly in the body.
- Use
wp_remote_postfor reliable HTTP requests. - Store the API key in
wp_options. - Handle JSON parsing for status codes.
Shortcode Implementation
Create a shortcode, such as [tts_speech], allowing content editors to insert voiceovers directly into posts. Pass the text content and voice selection as attributes. The plugin processes the input, calls the API, and returns the audio file (binary) or saves it to the media library. Since the API returns the file directly, you embed the player using the saved file URL.
- Shortcode:
[tts_speech voice="nova" text="Hello"]. - Supports standard WordPress text blocks.
- No external dependencies required.
Audio Player Embedding
Embed the generated audio using the standard HTML5 <audio> tag. Since the API returns the audio file directly, you can save it to the WordPress media library for reuse or stream it directly if caching is not enabled. The API does not provide a persistent URL for the file; you must store it. This ensures compatibility with all modern browsers and accessibility standards without needing third-party players.
- HTML5
<audio>tag support. - Direct file streaming or media library storage.
- Accessible controls by default.
Technical Requirements
To integrate the Melolo Labs TTS API into a WordPress environment, you must securely store your API key. Use environment variables or the WordPress wp_options table to keep the tts-... key hidden from client-side scripts. This prevents exposure in your theme’s HTML and ensures that only your server initiates requests to https://api.melolo.cc/v1.
HTTP requests should be handled server-side using PHP’s cURL or wp_remote_post to construct the JSON body with model, input, and voice parameters. Since the API processes requests sequentially, handle potential queue delays gracefully. Store the resulting audio file URL or binary data temporarily, then serve it to the user via a secure endpoint.
API Key Storage
Store the Bearer token in wp-config.php or the database, never in JavaScript. Rotate keys via the dashboard if compromised; the old key stops immediately.
Use WordPress’s update_option() for persistent storage, ensuring the key survives theme updates. Prefix keys with melolo_tts_key_ to avoid collisions.
- Use
wp-config.phpfor server-side keys - Prefix options with
melolo_to avoid conflicts - Never expose keys in frontend JS
HTTP Request Handling
Send POST requests to https://api.melolo.cc/v1/audio/speech with JSON bodies. Ensure input is under 4096 characters. Handle rate limits (60 req/min) by queuing requests if needed.
Parse the response body to save the audio file (mp3, wav, etc.) to your server’s upload directory. The API returns the full file in the response body, not a stream. Return the file path to the user via a shortcode or REST endpoint.
Use wp_remote_post for simplicity or cURL for advanced timeout handling. Always check for HTTP 200 status before processing audio data.
- Use
wp_remote_postorcURL - Validate JSON response status
- Queue requests to respect 60 req/min limit
Caching Strategies
Cache generated audio files locally to avoid repeated API calls for identical text. Use MD5 hashes of the text+voice+speed as filenames.
Implement a expiration policy: clear cache if text or voice changes. Use WordPress transients for temporary storage or object caching for high-traffic blogs.
Serve cached files directly via Nginx/Apache to reduce server load. This is critical for blogs with high read volumes.
- Cache audio by text+voice hash
- Use WordPress transients for temp storage
- Serve cached files via web server
Voice Selection for Blogs
Selecting the correct voice preset is critical for maintaining listener engagement in blog audio. The API offers eight distinct presets, ranging from the warm narrator tone of Aria to the energetic promo style of Felix. Each voice is optimized for specific content types, ensuring your audio matches the intended message without sounding robotic or out of place.
Choosing the Right Voice
For standard blog posts, Sage provides a calm, instructional tone suitable for tutorials, while Luna’s soft storytelling style works well for narrative content. Use Atlas for neutral news updates or Orion for deep, documentary-style segments. Avoid using Felix for long-form reading, as his high energy may become fatiguing for listeners over time.
- Aria: Warm, clear narrator for general content.
- Sage: Calm, instructional for tutorials.
- Luna: Soft, storytelling for narratives.
- Atlas: Neutral, suitable for news.
Language Detection
The API supports 23 languages, including English, Spanish, German, Japanese, Arabic, Chinese, Hindi, and others listed in the documentation. If you do not specify the language field, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script content, always set the language explicitly to ensure accurate pronunciation and avoid misinterpretation by the engine.
- Supports 23 languages including Arabic, Chinese, and Hindi.
- Default fallback is English for Latin scripts.
- Explicit language setting recommended for non-English text.
Tone Matching
Match the voice’s inherent character to your blog’s brand voice. Felix is energetic and promo-focused, making him ideal for product reviews or quick updates. Milo offers a friendly, conversational tone for personal blogs. Ensure the selected voice aligns with your content’s mood, as the API does not support emotion tags or custom tone adjustments.
- Felix: Energetic, promo-focused.
- Milo: Friendly, conversational.
- Orion: Deep, documentary style.
Performance Optimization
WordPress blogs often embed multiple audio segments, which can significantly impact page load times if not managed correctly. By caching generated audio files and implementing lazy loading strategies, developers can ensure that only necessary resources are loaded when a user scrolls to the content. This approach minimizes initial payload size and improves overall site performance.
Caching Audio Files
Store generated audio files locally or via CDN to avoid redundant API calls. Since the API charges per character, caching identical text outputs reduces both latency and costs. Use unique identifiers based on the text hash and voice selection to manage cache keys effectively.
- Cache by text hash and voice ID
- Use CDN for global distribution
- Invalidate cache only on text change
Lazy Loading Audio
Defer loading of audio players until they enter the viewport. This prevents blocking the main thread during initial page render. For blogs with long articles, this ensures that users on slower connections can read content without waiting for audio synthesis to complete.
- Use intersection observer for lazy loading
- Load placeholders instead of full audio
- Preload only near-visible sections
Bandwidth Management
Optimize audio formats to reduce data transfer. Selecting smaller file formats like Opus or MP3 over WAV or FLAC can significantly cut bandwidth usage. Additionally, compressing cached files where possible further reduces the data load on your server and users’ devices.
- Prefer Opus/MP3 for smaller size
- Compress cached audio files
- Monitor data transfer per request
Cost Management
Monitoring usage is straightforward because the API returns character counts with each response, allowing you to track consumption accurately. Since billing is based on a flat rate of $0.01 per 1,000 characters, you can calculate costs directly without complex tiered logic. Failed requests are free, ensuring you only pay for successful audio generation.
Monitoring Usage
You can monitor usage by checking your account dashboard at /get-api-key/. The API response does not specify headers with character counts; usage is tracked in the dashboard. Each request includes the character count, enabling precise tracking. Since failed requests are free, your actual spend aligns exactly with successful synthesis jobs.
- Check response headers for character count
- View balance in your account dashboard
- Failed requests incur zero cost
Optimizing Character Count
To minimize costs, optimize your blog content by removing unnecessary whitespace and punctuation before sending text to the API. Spaces and punctuation count as characters, so trimming redundant data reduces the input size. Since the limit is 4,096 characters per request, split long articles into manageable chunks to avoid errors and ensure efficient processing.
- Remove extra spaces and punctuation
- Split texts exceeding 4,096 characters
- Exclude redundant formatting tags
Budget Planning
With a clear understanding of the $10 per 1 million characters rate, you can forecast monthly expenses based on your blog's content volume. Start with the free trial credit to test integration, then top up via USDT (TRC-20) as needed. No minimum spend or monthly plans means you only pay for what you use, making it ideal for variable traffic.
- Rate: $0.01 per 1,000 characters
- Minimum top-up: $5 via USDT
- No monthly plans or subscriptions
Common Issues
WordPress blog developers often encounter predictable hurdles when integrating text-to-speech audio. These issues typically stem from network latency, API quota limits, or incorrect voice parameters. Understanding these common failure points helps you build more robust audio players.
API Timeout Errors
Longer texts may take several seconds to generate, potentially exceeding your WordPress plugin’s default HTTP timeout. If the generation queue is under load, requests may wait longer than expected.
- Increase your plugin’s HTTP timeout to at least 30 seconds.
- Implement retry logic with exponential backoff for transient network errors.
Rate Limit Exceeded
The API allows 60 requests per minute per key. If your blog generates audio on every page load for many users, you may hit this limit quickly. New accounts start with a lower 10 requests per minute limit.
- Cache generated audio files to avoid repeated API calls for the same text.
- Monitor your usage dashboard to anticipate high-traffic periods.
Invalid Voice ID
Using a voice ID not present in the current GET /v1/voices list will cause a 400 error. Ensure your WordPress configuration references one of the eight available presets (e.g., aria, nova, luna, sage, felix, milo, atlas, orion).
- Fetch the voice list dynamically before rendering the audio player.
- Validate voice IDs during your plugin’s settings save process.

Best Practices
For freelancers integrating TTS into WordPress, robust error handling prevents broken audio players. Catch HTTP failures and display graceful fallbacks, ensuring the blog remains readable even if synthesis stalls.
Design the user experience for immediate feedback. Show clear loading states during generation and provide simple controls to adjust speed or re-download files without reloading the page.
Error Handling
Implement retries for transient network issues. If the API returns a 429 rate limit error, queue subsequent requests or notify the user to retry later, avoiding immediate failures.
Validate character counts before sending requests. Since the limit is 4096 characters per request, split long blog posts programmatically to ensure complete audio generation without truncation.
- Retry failed requests with exponential backoff
- Validate input length against the 4096-character limit
- Return clear error messages to the frontend
User Experience Design
Use lazy loading to defer audio generation until the user clicks play. This saves API credits and reduces initial page load time, which is critical for WordPress performance.
Provide explicit controls for speed and format. Allow users to adjust the 0.25–4.0 speed range or select formats like mp3 for better compatibility with standard WordPress media players.
- Implement lazy loading for audio generation
- Expose speed and format controls
- Show clear loading indicators
Accessibility Compliance
Ensure generated audio players include standard ARIA labels. Screen readers should clearly identify the audio element and its current state, whether playing, paused, or buffering.
Provide text alternatives where possible. While TTS generates audio, offering a summary or transcript aids users who prefer reading or have specific accessibility needs.
- Add ARIA labels to audio controls
- Ensure keyboard navigability
- Provide text alternatives for audio content
Advanced Features
The API provides granular control over audio output through adjustable speed and format options. By tuning these parameters, developers can optimize playback for specific blog contexts, ensuring the content fits seamlessly into the reader's experience without requiring post-processing.
Batch processing allows freelancers to handle longer texts by splitting them into 4,096-character segments. You must join the returned audio files sequentially to create a complete track. This approach maintains quality while managing rate limits effectively for extensive blog posts.
Speed Adjustment
Adjust the speed parameter between 0.25 and 4.0 to match your blog’s pacing. Slower speeds improve clarity for instructional content, while faster rates suit quick news updates. This eliminates the need for external audio editing tools to adjust playback time.
The default speed is 1.0. Values outside the 0.25–4.0 range are rejected, ensuring consistent audio quality. This feature is particularly useful for creating varied audio experiences across different blog sections without re-recording.
- Range: 0.25 to 4.0
- Default speed: 1.0
- No audio quality loss within range
Format Selection
Choose from mp3, wav, opus, flac, or pcm using the response_format field. MP3 offers the best balance of quality and file size for web embedding, while WAV or FLAC suits high-fidelity requirements. OPUS provides efficient compression for mobile users.
PCM is available for uncompressed, raw audio needs. Each format serves different technical constraints, allowing you to optimize load times for your WordPress site without sacrificing audio clarity.
- Supported formats: mp3, wav, opus, flac, pcm
- MP3 recommended for web embedding
- OPUS for efficient mobile delivery
Batch Processing
For texts exceeding 4,096 characters, split the input into segments. Each segment generates a separate audio file. You can then join these files sequentially to create a complete audio track for your blog post.
This method respects the 60 requests per minute limit. By batching, you ensure that long articles are processed efficiently without hitting rate limits, maintaining a smooth workflow for automated content generation.
- Max input: 4,096 characters per request
- Segments joined sequentially
- Respects 60 req/min limit
Troubleshooting
Even reliable APIs encounter hiccups. When a request fails, inspect the HTTP status code and the JSON response body for specific error messages. Common issues include invalid voice IDs or text exceeding the 4096-character limit per request.
Debugging Requests
Use the provided curl example or your browser’s developer tools to log the exact payload sent to https://api.melolo.cc/v1. Verify that the Authorization header contains a valid tts-... key and that the model is either tts-1 or tts-1-hd.
- Check for 4xx errors indicating malformed requests or missing fields.
- Ensure text input does not exceed 4096 characters to avoid truncation errors.
- Verify the
voiceparameter matches one of the eight available presets.
Checking Balance
Navigate to your /get-api-key/ dashboard to view your current balance and character usage. Failed requests are free, so check your history to ensure credits were returned if synthesis failed. Note that the free trial credit expires after seven days.
- Monitor usage to stay within budget before triggering TRC-20 top-ups.
- Confirm that the displayed balance reflects recent top-ups, which may take minutes to process.
Support Contact
For issues beyond standard debugging, support is available exclusively via email. There is no phone number or live chat option. Please include your API key prefix and the request timestamp when emailing for assistance.
Future Updates
Melolo Labs continuously evaluates voice performance and user feedback to refine our existing eight presets. While we do not offer custom voice cloning, we periodically introduce new presets that better capture specific blogging tones, ensuring your content remains fresh without requiring infrastructure changes.
We also monitor API stability to ensure consistent delivery for your WordPress audio features.
New Voice Releases
We regularly assess our eight existing voices and may introduce new presets that better suit specific blog niches. These additions focus on enhancing narrative clarity and engagement for freelance developers.
API Enhancements
Updates primarily focus on stability and latency improvements. We do not plan to add SSML or streaming support. We prioritize reliable delivery of the current 8-voice, 8-format endpoint structure to maintain predictable integration workflows.
Documentation Updates
Our /docs/ page is updated whenever endpoint behaviors change or new usage examples become relevant. We ensure that code snippets for WordPress shortcodes and curl requests remain accurate for the latest API version.
Community Resources
Melolo Labs maintains an active ecosystem for developers integrating our TTS API into WordPress environments. While we do not host a dedicated community forum, the broader developer community shares practical insights on handling audio endpoints and managing character limits via open channels.
Staying connected with these resources helps freelancers troubleshoot common issues like rate limits or audio format selections more efficiently than waiting for email support.
Developer Forums
General WordPress and API discussions often feature threads on handling external audio services. Developers share tips on optimizing request payloads and managing API keys securely within WordPress configurations.
These forums serve as a primary place to find peer-reviewed solutions for edge cases not covered in our documentation.
- WordPress.org Support Forums
- Stack Overflow (tts-api tag)
- Reddit r/wordpress and r/webdev
Example Code Repos
GitHub hosts numerous open-source snippets demonstrating how to call our speech endpoint using the OpenAI SDK with a custom base URL. These repositories provide ready-to-use PHP functions for generating audio from post content.
Reviewing these code samples helps you understand best practices for error handling and caching audio responses in your theme’s functions.php file.
Tutorials
Various developer blogs offer step-by-step guides on building custom TTS plugins. These tutorials often cover shortcode implementation, audio player embedding, and managing character counts to stay within budget.
Following these guides ensures you avoid common pitfalls like exceeding the 4096-character limit or misconfiguring the authorization header.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence.
23 languages
Any voice speaks any of these languages.
