Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.marsgaming.info/v1. You can use this endpoint for all requests, including speech synthesis and voice listing. Ensure your client points to this specific domain to interact with the VoxHype text-to-speech service correctly.
How do I set my API key in requests?
Include your key in the Authorization header as a Bearer token. Use the format: Authorization: Bearer tts-... . Each account has one active key; issuing a new one immediately invalidates the old one, so update your headers promptly.
Can I use the OpenAI SDK with this API?
Yes. The request shape matches the OpenAI speech endpoint. Change the SDK’s base_url to https://api.marsgaming.info/v1 and use your VoxHype key. This allows you to leverage existing OpenAI SDK integrations for your streaming or voiceover workflows.
What is the maximum text length per request?
Each request supports up to 4096 characters. Spaces and punctuation count toward this limit. For longer scripts, split the text into chunks of this size and join the resulting audio files manually to ensure complete synthesis without data loss.
How do I specify the audio format?
Set the response_format field in your JSON body to mp3, wav, opus, flac, or pcm. This determines the output file type returned by the POST /v1/audio/speech endpoint. Choose formats compatible with your streaming software or editing pipeline.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key (10 before the first top-up). Requests are processed sequentially, so exceeding the limit may cause queuing delays. Monitor your usage to avoid timeouts during high-volume streaming or bulk voiceover generation.
Are failed requests charged?
No. If synthesis fails, the charge is returned in full. You only pay for successfully generated audio files. This ensures you are not billed for errors, making the pricing predictable for your content creation budget.
How do I rotate my API key?
Issue a new key from your account dashboard. The new key becomes active immediately, and the old one stops working at once. Update your applications to use the new key to maintain uninterrupted service without downtime.
Does the API support streaming audio?
No. The API returns complete audio files upon request completion. There is no WebSocket or real-time partial audio streaming. You must wait for the full synthesis to finish before receiving the file, which is suitable for pre-recorded streams.
Is there an SDK for mobile devices?
No. There is no mobile SDK. You can use the standard HTTP requests or the OpenAI SDK (with adjusted base_url) in any mobile environment that supports HTTP clients. The API is platform-agnostic and works with any capable device.
How do I handle text longer than 4096 characters?
Split your text into parts of up to 4096 characters. Send each part as a separate request and join the resulting audio files. This manual process ensures all content is synthesized, as the API does not handle long-form splitting automatically.
What is the default language if not specified?
If the language field is omitted, the system guesses from the script. Latin script defaults to English. For non-English Latin text, explicitly set the language parameter to ensure accurate pronunciation and avoid misinterpretation by the synthesis engine.
Can I adjust the speed of the voice in requests?
Yes. Set the speed field between 0.25 and 4.0. This allows you to speed up or slow down the narration to match your stream’s pacing. Adjustments apply to the generated audio file without affecting the voice character itself.
How do I get a list of available voices?
Send a GET request to /v1/voices. This endpoint returns details on all 8 presets, including their names, languages, and formats. Use this data to select a voice for your specific content type.
First request
curl
curl https://api.marsgaming.info/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.marsgaming.info/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.marsgaming.info/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 and Keys
Access the VoxHype API using a single Bearer token generated via your account dashboard. This key authenticates all requests to the API base URL and tracks your usage against your current balance.
Generating Your API Key
Keys are issued upon account creation via Google or email. The dashboard displays your active key, current balance, and character usage statistics for immediate reference.
- Sign up at /get-api-key/ to receive your first key.
- Keys are tied to your specific account balance.
- Only one key is active per account at any time.
Bearer Token Usage
Include the token in the Authorization header as Bearer tts-.... The API rejects requests without this header or with invalid tokens.
Key Rotation Policy
Issue a new key from the dashboard at any time. The previous key stops working immediately upon generation of the new one, ensuring secure access management.
Endpoint Overview
The API exposes three primary endpoints for streamers and developers. The core synthesis engine resides at the speech endpoint, while metadata endpoints provide details on available voices and model configurations.
POST /v1/audio/speech
Send text and receive audio files. This endpoint accepts JSON bodies with model, input, voice, and format parameters. It is the primary interface for generating synthetic speech for streams or videos.
GET /v1/voices
Retrieve a list of all available voice presets, supported languages, and audio formats. This helps you identify the 8 specific vocal identities (e.g., Aria, Nova, Atlas) suitable for your content style.
GET /v1/models
Fetch available model identifiers. This confirms the two options: 'tts-1' for standard generation and 'tts-1-hd' for higher fidelity, both using the same underlying engine and pricing structure.
Request Parameters
Configure your synthesis requests by selecting the appropriate model, input text, and voice preset. The API accepts two engine variants and handles text up to a strict character limit per call.
Model Selection (tts-1, tts-1-hd)
Both "tts-1" and "tts-1-hd" use the same underlying engine and carry identical pricing. Choose "tts-1-hd" only if your streaming quality requirements demand higher fidelity, as the audio quality difference is the primary distinction.
Input Text Limit (4096 Chars)
Each request accepts a maximum of 4,096 characters, including spaces and punctuation. For longer stream intros or commentary, split your text into chunks and concatenate the resulting audio files.
Voice Preset Selection
Select one of eight presets to define vocal identity. Use "aria" for clear narration, "nova" for upbeat highlights, or "atlas" for neutral news-style updates. All voices support all 23 available languages.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Audio Response Formats
Each generated audio file carries an inaudible watermark that marks it as synthetic speech. The API returns the audio data directly in the response body, allowing you to save it immediately. Generated audio is not stored on our servers.
MP3 Compatibility
MP3 is the default and most widely supported format for streaming platforms and video editors. It provides a good balance between file size and quality, making it ideal for quick uploads to Twitch or YouTube.
WAV Lossless Quality
WAV offers uncompressed audio, preserving every detail of the synthetic voice. Use this format when you need to edit the audio further in a DAW or require the highest fidelity for professional voiceover work.
OPUS and FLAC Options
OPUS provides efficient compression suitable for real-time applications, while FLAC offers lossless compression for archiving. Both formats maintain audio integrity without the large file sizes of WAV, giving you flexibility based on your storage needs.
Rate Limits and Quotas
Rate limits protect API stability during high-volume streaming events. Each API key is capped at 60 requests per minute for standard usage, ensuring consistent performance for your automated voiceover pipelines.
60 Requests Per Minute
Once you top up your USDT balance, your key operates at the full 60 requests/minute quota.
Pre-Top-Up Limit (10/min)
New accounts or those without a recent top-up start with a reduced limit of 10 requests per minute. This lower threshold helps prevent resource exhaustion during the initial testing phase or free trial period.
Queue Processing Behavior
Requests are processed sequentially. Requests are processed one after another, so under load a request may wait in a queue. Under heavy load, generation may take longer than real-time, so plan your stream triggers accordingly.
- Sequential processing ensures audio integrity.
- Queued requests are processed in order.
- Delays increase during high traffic periods.

OpenAI SDK Integration
The official OpenAI Python and Node SDKs work directly with our API. You simply point the client to our base URL instead of OpenAI's. This allows you to use familiar methods like Audio.speech.create without rewriting your integration logic.
Configure the base_url to https://api.marsgaming.info/v1 and provide your tts-... key. The request shape matches the OpenAI speech endpoint exactly, ensuring seamless drop-in replacement for existing TTS workflows.
Changing Base URL
Update your SDK configuration to use https://api.marsgaming.info/v1 as the base URL. This directs all requests to our infrastructure while maintaining standard OpenAI-compatible paths.
- Set
base_urlin your SDK client instance. - Keep the path
/v1/audio/speechunchanged.
Using Official SDKs
The standard OpenAI SDKs handle our endpoints correctly. Pass your API key in the Authorization header as Bearer tts-.... The SDK manages retries and encoding automatically.
- Supports Python and Node.js environments.
- Uses standard
Audio.speech.createmethods.
Compatibility Notes
Our models tts-1 and tts-1-hd map directly to OpenAI's naming convention. Ensure your SDK version supports the audio speech endpoint. All standard parameters like voice, model, and response_format are fully compatible.
No custom SDK is required. You can use any HTTP client, but the official SDKs simplify header and authentication handling for gaming streams and VTuber bots.
- No additional libraries needed.
- Works with standard JSON payloads.
Error Handling
The API returns standard HTTP status codes to indicate request outcomes. A 400 error indicates invalid input, such as text exceeding the 4096-character limit or an unsupported voice. A 401 error means your Bearer token is missing or invalid, requiring you to verify your key in the dashboard. A 429 error signals that you have exceeded the rate limit of 60 requests per minute.
Unlike standard services, failed synthesis requests do not consume your balance. If the server returns an error status other than 400 (indicating client-side issues like bad format), the charge is returned in full. This ensures you only pay for successfully generated audio files, protecting your credits during temporary service instability.
Common HTTP Errors
A 400 Bad Request occurs when the input is malformed, such as exceeding the 4096-character limit or providing an invalid voice preset. A 401 Unauthorized error indicates your API key is missing or expired. A 429 Too Many Requests error appears when you exceed the 60 requests per minute limit per key.
- 400: Invalid input or character limit exceeded
- 401: Missing or invalid Bearer token
- 429: Rate limit exceeded (60 req/min)
Failed Request Refunds
If synthesis fails due to a server issue, the charge is returned in full. You only pay for successful audio generations. This policy protects your balance during temporary outages or processing errors.
Retry Logic
Implement exponential backoff for 429 and 500 errors. Wait briefly before retrying, as requests are processed sequentially. Under load, a request may wait in a queue, so immediate retries may still hit rate limits. Always check the response body for specific error details.
- Use exponential backoff for 429/500 errors
- Check response body for error details
- Avoid immediate retries during high load
Curl Example for Immediate Testing
Test the API immediately with these cURL commands. Replace YOUR_API_KEY with your key from the dashboard. These examples cover basic synthesis, voice selection, and audio file retrieval.
Basic Text Request
Send a simple text-to-speech request using the default model and voice.
- ```bash curl -X POST "https://api.marsgaming.info/v1/audio/speech" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello, streamers! This is a test.", "voice": "nova"}' \ -o output.mp3 ```
Specifying Voice and Speed
Customize the output by selecting a specific voice preset and adjusting the playback speed. The speed parameter accepts values between 0.25 and 4.0.
- ```bash curl -X POST "https://api.marsgaming.info/v1/audio/speech" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1-hd", "input": "Fast-paced commentary for the match!", "voice": "felix", "speed": 1.5}' \ -o commentary.mp3 ```
Downloading the Audio File
The API returns the audio file directly in the response body. Use the -o flag to save it locally. Supported formats include mp3, wav, opus, flac, and pcm.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. We check for listener fatigue, ensuring the voice remains pleasant and clear during hour-long streams without becoming grating.
23 languages
Any voice speaks any of these languages.
