Frequently asked questions
What is the correct base URL for the API?
The API base URL is https://api.g2gmega.cc/v1. You send POST requests to https://api.g2gmega.cc/v1/audio/speech for speech synthesis. Use GET /v1/voices to list available voices and GET /v1/models for model details. This endpoint structure matches the OpenAI speech endpoint format.
How do I authenticate with the API?
Include your API key in the Authorization header as Bearer tts-... . Each account has one active key. If you issue a new key, the old one stops immediately. You can find your key and balance on the /get-api-key/ page after signing in.
What happens if I exceed the rate limit?
You are limited to 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so under load, requests may wait in a queue. Exceeding the limit typically results in a 429 Too Many Requests error.
Can I use the OpenAI SDK with this API?
Yes. The request shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.g2gmega.cc/v1 and providing your site-specific API key. This allows seamless integration for developers already familiar with the OpenAI ecosystem.
How do I specify the voice in the request?
Include the voice parameter in your JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. You can view all available voices and their details by making a GET request to /v1/voices.
Is the response always an audio file?
Yes, a successful request returns an audio file. You can choose the format using the response_format parameter: mp3, wav, opus, flac, or pcm. Failed requests return an error object and are free of charge.
What is the maximum input length?
The maximum input length is 4096 characters per request. For longer texts, split them into parts of up to 4096 characters and join the resulting audio files. Spaces and punctuation count toward the character limit.
Does the API support streaming audio?
No, the API does not support streaming, WebSocket, or real-time partial audio. It returns the complete audio file after synthesis is finished. Short phrases may take a few seconds, while longer texts take roughly real-time duration.
How do I handle errors in my code?
Check the HTTP status code. A 429 indicates rate limit exceeded. A 401 indicates authentication errors. Failed synthesis requests are free, so you are not charged if the audio generation fails. Always handle network errors gracefully.
Can I generate multiple voices in one request?
No, each request generates audio for a single voice. To use multiple voices, send separate requests for each voice. You can then join the resulting audio files programmatically if needed for your workflow.
Is the API key case-sensitive?
Yes, API keys are case-sensitive. Ensure you copy the key exactly as shown on the /get-api-key/ page. The key format begins with tts- followed by alphanumeric characters.
Do I need to renew my API key?
No, your API key does not expire. You can issue a new key at any time from the /get-api-key/ page. When you issue a new key, the old one stops working immediately.
How do I know which voices are available?
Make a GET request to /v1/voices. This endpoint returns a list of all available voices, their associated languages, supported formats, and pricing details. You can also refer to the product facts for the eight preset voices.
What is the speed parameter range?
The speed parameter accepts values between 0.25 and 4.0. The default speed is 1.0. Adjusting the speed affects the generation time but not the character count or price. Values outside this range will result in an error.
First request
curl
curl https://api.g2gmega.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.g2gmega.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.g2gmega.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
Authentication is handled via a Bearer token sent in the Authorization header of every request. You receive a single API key when you sign up, which grants access to your account’s voice generation capabilities.
Bearer token in header
Include your key as Authorization: Bearer tts-... in each POST request to /v1/audio/speech. The OpenAI SDKs work seamlessly by setting the base URL to https://api.g2gmega.cc/v1 and passing this key.
One active key per account
Your account holds one active key at any time. This key controls access to your balance and usage limits.
Revoke key on demand
You can issue a new key from your dashboard at any time. The old key stops working immediately, ensuring you can quickly secure your account if needed.
Endpoint: /v1/audio/speech
The core of VocalPress is the speech generation endpoint. Send a POST request to the API base URL to convert your blog post text into audio. This single endpoint handles all synthesis tasks, returning the generated voiceover directly in the response.
POST request structure
Direct your requests to https://api.g2gmega.cc/v1/audio/speech. The endpoint accepts a JSON payload containing your text, voice selection, and format preferences. It follows the same request shape as the OpenAI speech endpoint, allowing you to use standard HTTP clients or the official OpenAI SDK by simply adjusting the base URL.
JSON body parameters
Include input (up to 4096 characters), model (tts-1 or tts-1-hd), voice (one of eight presets), response_format, and optional speed. Longer texts must be split into parts and joined manually. Each request is processed sequentially, so under load, synthesis may wait in a queue before generating audio.
- Model: tts-1 or tts-1-hd
- Input: max 4096 characters
- Voice: 8 preset options
- Speed: 0.25–4.0 range
Response with audio file
On success, the API returns the audio file directly in the response body with the appropriate Content-Type header (e.g., audio/mpeg for MP3). Failed requests return no audio but provide error details. The generated audio is not stored on our servers; it is delivered instantly to your request.
Parameters: Model and Voice
Choose between tts-1 and tts-1-hd for synthesis. Both engines deliver identical pricing at $0.01 per 1,000 characters. Select tts-1-hd if you prefer the HD model; the price is the same as tts-1.
8 preset voices available
Select from eight distinct presets to match your content’s tone. Female voices include aria (warm narrator), nova (bright), luna (soft storyteller), and sage (calm instructional). Male options feature felix (energetic promo), milo (friendly), atlas (neutral news), and orion (deep documentary).
- 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
Language code specification
Support covers 23 languages including English, Spanish, German, French, Japanese, and Chinese. Any voice can speak any supported language. If you omit the language field, the system guesses the language from the script, defaulting to English for Latin text.
- Set
languageexplicitly for non-English Latin text - Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
- Not supported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali
Response Format Options
The API supports five standard audio formats: MP3, WAV, OPUS, FLAC, and PCM. You specify the desired output type using the response_format parameter in your request body. This allows you to balance file size and quality based on your WordPress blog’s needs.
Generated audio is returned as binary data within the HTTP response. The server sets the Content-Type header to match the requested format, ensuring your client or browser can correctly identify and save the file.
MP3, WAV, OPUS, FLAC, PCM
Choose MP3 for efficient web delivery or WAV/FLAC for lossless quality; OPUS and PCM are also available. OPUS and PCM are also available for specific use cases. All formats handle the full range of supported voices and languages.
- MP3: Compressed, ideal for web players
- WAV/FLAC: Lossless, higher fidelity
- OPUS/PCM: Alternative compression or raw audio
Binary audio in response
The response body contains the raw audio bytes directly. No additional JSON wrapper surrounds the audio data. This allows saving to disk.
Content-Type header details
The server automatically sets the Content-Type header to the correct MIME type (e.g., audio/mpeg for MP3). This ensures compatibility with standard HTTP clients and media players.
Rate Limits
Your API key allows 60 requests per minute once your account is active. This limit applies to the /v1/audio/speech endpoint and resets every minute. If you exceed this, you receive a 429 error. For WordPress bloggers generating audio for multiple posts, this rate is sufficient for standard publishing workflows without requiring complex batching strategies.
When you first create an account, your limit is lower. You can make 10 requests per minute until you complete your first top-up. This allows you to test the API and verify voice quality before committing to a larger volume of content generation.
60 requests per minute
Once activated, you can send up to 60 synthesis requests per minute. This applies to all requests made with your active key. If you need to generate audio for a long article, you can split the text into parts and send them sequentially within this limit.
- Limit resets every 60 seconds
- Applies to all endpoints using the same key
- No distinction between tts-1 and tts-1-hd
10 requests before first top-up
New accounts start with a lower limit of 10 requests per minute. This allows you to test the API with your free trial credit. Once you add funds via USTRC-20, your limit increases to 60 requests per minute immediately.
- Applies to new accounts only
- Increases after first top-up
- No minimum spend required
Queue behavior under load
Requests are processed in the order they are received. If you send many requests at once, they may wait in a queue. Short phrases take a few seconds, while longer texts take time proportional to their length. You may experience slight delays during high traffic periods.
- Requests are processed sequentially
- Delays depend on text length
- No guaranteed real-time response

Error Handling
When your API key is invalid or missing, the server returns a 401 status. Ensure your Authorization: Bearer tts-... header matches the key issued in your dashboard. If you revoked a key or generated a new one, the previous key stops immediately.
Check your network proxy or firewall if 401 persists despite correct credentials. The error response includes a clear message confirming the authentication failure, allowing you to verify your key string in the account dashboard before retrying.
401 Unauthorized for bad key
The API returns a 401 status code if the Bearer token is missing, malformed, or no longer active. Since each account holds only one active key at a time, revoking or generating a new key invalidates the old one instantly. Verify your key in the /get-api-key/ dashboard.
Ensure no extra whitespace exists in your header value. The authentication check is strict; even a trailing space can cause failure. Use the provided curl example to test connectivity with your current key before integrating into your application.
- Missing
Authorizationheader - Expired or revoked key
- Malformed token string
429 Too Many Requests
Exceeding the limit of 60 requests per minute triggers a 429 status. New accounts start with a 10 requests per minute limit until the first top-up. Requests are processed sequentially, so under load, additional requests may queue, eventually timing out if the limit is severely exceeded.
Implement exponential backoff in your client code to handle temporary throttling gracefully. Monitor your usage dashboard to anticipate high-volume periods and adjust your request frequency accordingly to avoid unnecessary delays in audio generation.
- Standard limit: 60 req/min
- Trial limit: 10 req/min
- Sequential processing under load
500 Internal Server Error
A 500 status indicates a transient server issue during synthesis. Failed requests are free, and any charged amount is returned in full. Retry the request after a short delay, as the issue is likely temporary and not related to your input parameters.
If the error persists, verify your text input does not exceed 4096 characters and that the selected voice and language are valid. Contact support via email if the issue remains unresolved after multiple retries.
- Transient synthesis failure
- Charges refunded automatically
- Retry with exponential backoff
cURL Example
Generate audio by sending a POST request to the speech endpoint. The API accepts your text input and returns the synthesized audio file directly in the response body. This method works for any text under the 4096-character limit.
Use cURL to test the endpoint quickly. The command below sends a request using the 'nova' voice in English. Replace the placeholder key with your actual API token from the dashboard.
Basic request command
Send a standard POST request with your text and voice selection.
The response contains the audio data directly, allowing immediate playback or storage.
- Endpoint: POST https://api.g2gmega.cc/v1/audio/speech
- Auth: Bearer <your-api-key>
- Body: JSON with 'model', 'input', 'voice'
Saving audio to file
Redirect the output to a file using the -o flag. This creates an MP3 file you can play locally or embed in your WordPress posts.
Ensure the filename matches the requested response_format for correct playback.
- Command: curl -X POST ... -o output.mp3
- Supports mp3, wav, opus, flac, pcm
Error output inspection
If the request fails, check the HTTP status code. A 401 error indicates an invalid or expired API key.
A 429 error means you have exceeded the rate limit of 60 requests per minute.
OpenAI SDK Integration
The OpenAI Python SDK works directly with VocalPress by overriding the default connection endpoint. Since the API follows the same request shape as OpenAI’s speech endpoint, you can use the official library without needing a custom client or wrapper.
Simply configure the client to point to the API base URL and provide your unique key. This approach lets you generate audio files in Python using familiar methods, keeping your code clean and standard.
Change base_url to api.g2gmega.cc
Set the base_url parameter to https://api.g2gmega.cc/v1 when initializing the OpenAI client. This directs all API calls to VocalPress infrastructure instead of OpenAI’s servers.
Ensure you specify the API version or leave it blank depending on the SDK version. The endpoint structure remains identical, so existing code patterns for speech generation require minimal adjustment.
Use official OpenAI SDK
The official OpenAI Python package handles the request formatting and authentication automatically. You use the standard client.audio.speech.create() method, passing your text, voice, model, and other parameters.
This method supports all standard parameters like response_format and speed. The library manages the binary response, allowing you to easily save the audio file to disk.
Pass custom API key
Initialize the client with your specific VocalPress key using the api_key argument. This key authenticates your requests against the VocalPress rate limits and billing system.
Use the key from your dashboard’s /get-api-key/ page. The SDK sends this key in the Authorization header, ensuring your usage is tracked correctly against your account balance.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Her tone works best for personal essays or lifestyle blogs where connection matters.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- FFmpeg documentation
- TRON developer hub: TRC-20
- OpenAI API reference: create speech
- openai-python on GitHub
- MDN: Web Speech API
- curl documentation
- Node.js documentation
- Creative Commons Attribution 4.0
- LibriVox public-domain audiobooks
- W3C WAI: making audio and video accessible
- ISO 639 language codes
