Text-to-Speech API: Quickstart for Streamers and Devs

By VoxHype editorial team · Updated 2026-11-19

This quickstart guides streamers and developers through integrating the VoxHype text-to-speech API into their content workflows. You will learn how to generate audio files for VTuber avatars, stream overlays, and voiceovers using the same request structure as the OpenAI speech endpoint. We cover authentication, parameter selection, and SDK integration with concrete examples tailored for gaming and broadcast environments.

By the end of this page, you will have a working curl command to synthesize speech, understand rate limits, and manage your API key. You will also see how to handle errors, rotate keys, and choose the right audio format for your platform. This guide focuses on practical implementation details, ensuring you can deploy synthetic voices quickly without unnecessary complexity.

Text-to-Speech API: Quickstart for Streamers and Devs

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.mp3

Python (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
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication and Keys

Sound wave illustration for: 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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.
Rate Limits and Quotas

OpenAI SDK Integration

Sound wave illustration for: 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_url in your SDK client instance.
  • Keep the path /v1/audio/speech unchanged.

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.create methods.

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

Sound wave illustration for: 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

Sound wave illustration for: 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.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. Creative Commons Attribution 4.0
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. ISO 639 language codes
  5. Tether (USDT)
  6. IETF RFC 7845: Ogg Opus
  7. TRON developer hub: TRC-20
  8. LibriTTS-R corpus (OpenSLR 141)
  9. MDN: Web Speech API
  10. openai-node on GitHub
  11. OpenAI API reference: create speech
  12. curl documentation

More on this site