Frequently asked questions
What is the API endpoint?
Send a POST request to https://api.melolo.cc/v1/audio/speech with a JSON body containing your text, voice selection, and format preferences. The endpoint accepts standard parameters like model, input, voice, and response_format, following the same structure as the OpenAI speech endpoint for easy integration.
How do I authenticate?
Include your API key in the request header using the format Authorization: Bearer tts-... . Each account holds one active key at a time. If you issue a new key, the previous one stops working immediately, ensuring secure access to your text-to-speech generation services.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work seamlessly. You only need to change the base_url to https://api.melolo.cc/v1 and use your Melolo API key. This allows you to leverage familiar SDK methods for generating audio without rewriting your integration logic or learning a new client library.
What is the rate limit?
The limit is 60 requests per minute per key. New accounts start with a lower limit of 10 requests per minute until the first top-up is processed. This ensures fair usage while allowing you to scale your volume as your project grows and requires more audio generation.
How do I get an API key?
Sign up on the /get-api-key/ page using Google or an email and password. Your account page displays your active key, balance, and usage stats. Accounts created via Google receive a $0.50 free trial, while email-based accounts start without trial credit.
What formats are supported?
You can choose from mp3, wav, opus, flac, or pcm for your audio output. Specify your preferred format in the response_format field of your request. This flexibility allows you to select the best balance between file size and quality for your specific blog or WordPress audio features.
How do I handle errors?
Failed requests are free. Monitor your response status to identify issues. Since requests are processed sequentially, under load you may experience delays, but the system ensures you are not billed for audio that does not generate successfully.
What is the character limit per request?
Each request supports up to 4096 characters of input text. For longer texts, split them into parts of this size and join the resulting audio files. Spaces and punctuation count toward the character limit, so plan your splits accordingly to ensure seamless audio playback for your audience.
Can I change my API key?
Yes, you can issue a new API key at any time from your account page. When a new key is generated, the old one stops working immediately. This allows you to rotate keys for security purposes without downtime, ensuring your integrations remain secure and up-to-date.
Is there a WebSocket endpoint?
No, there is no WebSocket endpoint or streaming support. The API returns the complete audio file in the response after processing. You must wait for the full generation to complete before receiving the audio data.
Do I need a custom SDK?
No, you do not need a custom SDK. The API follows the same request shape as the OpenAI speech endpoint, allowing you to use the official OpenAI SDK or plain HTTP requests. This simplifies integration for developers who already have existing infrastructure built around standard TTS protocols.
How do I stream audio?
Streaming is not supported. The API returns the entire audio file in the response body after synthesis is complete. You cannot receive partial audio chunks in real time.
What is the base URL?
The base URL for all API requests is https://api.melolo.cc/v1. Use this URL when configuring your SDK or making direct HTTP calls. All endpoints, including speech generation and voice listing, are relative to this base, ensuring consistent routing for your text-to-speech integration across different environments.
How do I parse the response?
The response contains the generated audio file in the format you requested. For errors, the response includes details about the failure. Since failed requests are free, you can safely retry. Ensure your code handles the binary audio data or file stream appropriately.
First request
curl
curl https://api.melolo.cc/v1/audio/speech \
-H "Authorization: Bearer $TTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
--output hello.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.melolo.cc/v1", api_key="tts-...")
with client.audio.speech.with_streaming_response.create(
model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
response.stream_to_file("hello.mp3")Node.js (openai)
import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ baseURL: "https://api.melolo.cc/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));| voice | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Authentication
Secure access to the Melolo Labs TTS API relies on a single active API key passed as a Bearer token in the Authorization header. This token authenticates your requests to the speech generation endpoint, ensuring that usage is tracked against your account balance.
Bearer Token Setup
Include your key in every request using the standard HTTP header format: Authorization: Bearer tts-.... This method is compatible with all standard HTTP clients and the OpenAI SDK, requiring no complex OAuth flows or session management.
API Key Generation
Keys are generated when you sign up via Google or email on the /get-api-key/ page. Each account maintains one active key, which is displayed immediately upon creation. You can generate a new key at any time, which becomes active instantly.
Key Revocation
Revoking a key is immediate. When you issue a new key, the previous one stops working at once. This allows you to invalidate compromised keys instantly without waiting for a cooldown period or manual approval from support.
Endpoints Overview
The API exposes three primary endpoints for generating audio and managing resources. The speech endpoint handles synthesis, while the voices and models endpoints provide metadata about available capabilities and pricing structures.
Speech Generation Endpoint
Send text to POST https://api.melolo.cc/v1/audio/speech. Accepts JSON bodies with model, input, voice, and format parameters. Returns an audio file directly in the response body.
- Endpoint: POST /v1/audio/speech
- Input: JSON with text up to 4096 characters
- Output: Audio file (mp3, wav, opus, flac, pcm)
Voices Listing Endpoint
Retrieve available voices, languages, and formats via GET /v1/voices. Returns a list of the 8 preset voices with their associated metadata, including supported languages and formats.
- Endpoint: GET /v1/voices
- Returns: Voice list, languages, formats, prices
- Use: Identify available options before synthesis
Models Endpoint
Access model details with GET /v1/models. This endpoint confirms the available engine versions (tts-1 and tts-1-hd), which share the same engine and pricing structure.
- Endpoint: GET /v1/models
- Models: tts-1, tts-1-hd
- Pricing: Identical for both models
Request Parameters
The API accepts plain text input with a strict limit of 4,096 characters per request. Spaces, punctuation, and special symbols are counted toward this total. For longer content, split the text into chunks and concatenate the resulting audio files manually.
Ensure your input text matches the target language. If the language field is omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language code prevents mispronunciation for non-English Latin-script inputs.
Input Text Field
Pass the text via the input field in the JSON body. The API processes requests sequentially, so long texts may experience slight delays. Each request generates audio at roughly real-time speed, averaging 25 characters per second.
- Maximum length: 4,096 characters
- Characters include spaces and punctuation
- Use
languageparameter for non-English Latin text
Voice Selection
Choose from eight presets: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, or Orion. Any voice can speak any of the 23 listed languages. Select the voice ID that best matches your tone, such as 'Atlas' for news or 'Nova' for upbeat content.
Voices are derived from licensed recordings and include an inaudible synthetic watermark. You can adjust the speed between 0.25 and 4.0 to fit your video or blog pacing needs.
- 8 voice presets available
- Supports 23 languages
- Speed range: 0.25–4.0
Response Format
Specify the audio format using the response_format field. Options include mp3, wav, opus, flac, and pcm. MP3 is recommended for web delivery due to its small file size, while WAV offers uncompressed quality.
The API returns the audio file directly in the response body. Ensure your client handles binary data correctly to avoid corruption.
- Formats: mp3, wav, opus, flac, pcm
- MP3 best for web use
- WAV for lossless quality
OpenAI SDK Integration
Leverage the official OpenAI SDKs by simply redirecting the base URL to our API endpoint. This allows you to use familiar libraries without learning a new client wrapper, ensuring a smooth transition for developers already accustomed to the OpenAI request structure.
Configure the client to point at https://api.melolo.cc/v1 and supply your Melolo API key. The request shape remains identical to the standard speech endpoint, meaning your existing integration code works with minimal adjustments.
Base URL Configuration
Set the base_url parameter in your SDK client to https://api.melolo.cc/v1. This directs all API calls to Melolo Labs while maintaining the standard OpenAI endpoint paths.
Client Initialization
Initialize the client using your unique Bearer token obtained from your dashboard. Ensure the token is passed in the Authorization header as Bearer <your_key>.
Speech Generation Call
Invoke the standard speech method with your text, selected voice, and desired response format. The SDK handles the JSON payload construction automatically, returning the audio file directly.
Curl Example
The curl command provides a direct way to verify the API works before writing code. This method confirms your authentication and voice selection are correct.
Basic Request Command
Use this command to send a short text string to the speech endpoint. Replace YOUR_API_KEY with your actual key.
Headers Configuration
Include the Bearer token in the Authorization header. Set Content-Type to application/json to ensure the server parses the input correctly.
Response Parsing
The response contains the audio file directly. Save the output using the -o flag to generate the final audio file on your system.

Rate Limits
Rate limits protect service stability and ensure fair usage across all accounts. Your API key is the limiting factor, allowing 60 requests per minute once fully active.
60 Requests Per Minute
The standard limit is 60 requests per minute per key. If you exceed this threshold, subsequent requests will be rejected until the window resets. Long texts split into multiple chunks count as individual requests, so plan your batching accordingly.
Initial Limit of 10 RPM
New accounts start with a reduced limit of 10 requests per minute. This lower threshold helps verify your integration stability before allowing higher throughput. You can test your setup comfortably within this range without worrying about immediate throttling.
Limit Increase After Top-Up
The limit increases to 60 RPM automatically after your first top-up. Once you add USDT via TRC-20, the system recognizes your active status and raises the cap. This happens within minutes of the transfer confirmation, requiring no manual support ticket.
Error Handling
Handling failures gracefully ensures your audio pipeline remains robust. Our API returns standard HTTP status codes to indicate success or specific failure types, allowing you to implement precise error handling in your application logic without guessing the cause of a failure.
Common Error Codes
Use the HTTP status code to determine the next step. A 401 Unauthorized indicates an invalid or expired API key, requiring you to verify your credentials. A 429 Too Many Requests signals that you have exceeded the rate limit of 60 requests per minute.
- 400: Bad Request (invalid JSON or missing fields)
- 401: Unauthorized (invalid or revoked key)
- 429: Too Many Requests (rate limit exceeded)
Retry Logic
Implement exponential backoff for 429 and 500 errors. Since requests are processed sequentially, brief delays help avoid queueing conflicts during high load. Do not retry immediately on 401 errors, as the key is likely invalid.
Character Limit Errors
Each request supports a maximum of 4096 characters in the input field. Exceeding this limit returns a 400 error. You must split longer texts into chunks of 4096 characters or fewer before sending them to the API.
Response Format
The API returns the generated audio file directly in the response body, allowing you to save the content immediately. There is no need to poll for a separate download URL.
Audio File Return
You receive the raw audio data immediately upon successful synthesis. This direct return simplifies integration, as you can pipe the response directly into a player or save it to your storage without intermediate steps.
Metadata Included
The response includes standard HTTP headers and metadata confirming the request status. While the audio is the primary payload, the system logs request time, character count, and status for your billing records.
Content-Type Headers
The Content-Type header accurately reflects the format you requested, such as audio/mpeg for MP3 or audio/wav for WAV. This ensures your application handles the binary data correctly without manual decoding.
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.
Sources and further reading
- Wikipedia
- OpenAI API reference: create speech
- LibriVox public-domain audiobooks
- TRON developer hub: TRC-20
- Python documentation
- Node.js documentation
- Creative Commons Attribution 4.0
- openai-node on GitHub
- IETF RFC 7845: Ogg Opus
- LibriTTS-R paper (arXiv 2305.18802)
- Tether (USDT)
- W3C WAI: making audio and video accessible
