Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or an email and password. Once registered, your dashboard displays your unique API key, current balance, and usage statistics. You can also generate a new key at any time, which immediately invalidates the previous one.
What is the endpoint URL?
Send your requests to POST https://api.playh95.com/v1/audio/speech. This endpoint accepts JSON bodies containing your text, voice selection, and format preferences. You can also retrieve available voices and models via GET /v1/voices and GET /v1/models respectively.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work seamlessly. Simply change the base_url to https://api.playh95.com/v1 and provide your VoiceGrid API key. This allows you to use the same request shape as the OpenAI speech endpoint without needing a custom client library.
What is the character limit?
Each request supports up to 4096 characters of input text. For longer texts, split your content into chunks of this size and join the resulting audio files. Spaces and punctuation count toward the character limit used for billing calculations.
How do I set the language?
Pass an optional ISO language code in the request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language is recommended for non-English Latin-script text to ensure accuracy.
What models are available?
Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing. You can select either model in your request body based on your preference, as they use the same engine and pricing.
What audio formats are supported?
You can request audio in mp3, wav, opus, flac, or pcm formats. Specify your preferred format using the response_format field in your JSON request body. The API returns the generated audio file directly in the response according to your selected format.
What are the rate limits?
You are limited to 60 requests per minute per API key. New accounts without top-ups start with a lower limit of 10 requests per minute. Requests are processed sequentially, so high load may cause queuing delays for your synthesis jobs.
How do I handle errors?
If synthesis fails, the charge is returned in full, so you are not billed for unsuccessful attempts. Monitor your response status codes to detect issues. Failed requests do not consume your character balance, ensuring you only pay for successfully generated audio.
How do I authenticate?
Include your API key in the Authorization header as a Bearer token: Authorization: Bearer tts-... . Each account has one active key at a time. Ensure your key is valid and active before sending requests to the API endpoint.
Can I change my API key?
Yes, you can issue a new API key at any time from your dashboard. When a new key is generated, the old one stops working immediately. This allows you to rotate keys securely without downtime for your integrated applications.
What happens if I exceed limits?
Requests are processed one after another, so exceeding the per-minute limit may cause your requests to wait in a queue. You will still be charged only for successful generations. Ensure your implementation handles potential delays gracefully during high-load periods.
First request
curl
curl https://api.playh95.com/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.playh95.com/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.playh95.com/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 |
Quickstart with curl
Integrate VoiceGrid’s text-to-speech engine into your chatbot or voice assistant with just a few lines of code. This guide shows you how to generate audio files using standard HTTP requests, ensuring you get started quickly without complex dependencies.
Get your API key
Navigate to the /get-api-key/ page and sign in with Google or an email account. Your unique Bearer token appears immediately, ready to be copied into your environment variables or code.
Make your first request
Send a POST request to the speech endpoint with your JSON payload. Include your Authorization: Bearer header, the model (e.g., tts-1), the input text, and the desired voice. The API returns the audio file directly in the response body.
You can test this instantly with a simple curl command using one of the eight voice presets like nova or atlas.
- Endpoint: POST https://api.playh95.com/v1/audio/speech
- Method: POST
- Content-Type: application/json
Parse the audio response
The response body contains the raw audio data, not JSON. Save this binary output directly to a file with the specified response_format (mp3, wav, opus, flac, or pcm).
Since the audio is returned in the response body, you can save it for later playback or pass it to your application’s audio player.
Using the OpenAI SDK
Integrating VoiceGrid into your chatbot or voice assistant is straightforward because the API mirrors the OpenAI speech endpoint structure. You do not need a custom client library; the official OpenAI SDKs handle the heavy lifting for you.
Change base URL
Point your SDK client to the VoiceGrid API base URL: https://api.playh95.com/v1. This single change redirects all requests to our TTS engine while keeping your existing code logic intact.
Use official SDKs
You can use the standard OpenAI Python, Node.js, or other language SDKs. Simply initialize the client with your tts-... Bearer token and the new base URL. This ensures compatibility with the ecosystem you likely already know.
Same request shape
The JSON body for POST /v1/audio/speech uses the exact same fields as OpenAI: model, input, voice, response_format, and speed. Your existing integration scripts will work with minimal adjustments, just swapping the endpoint.

Request parameters
To generate speech, send a POST request to /v1/audio/speech with your chosen model, input text, and voice preset. The API accepts standard JSON bodies, making integration straightforward for indie developers building chatbots or voice assistants.
Model selection
Choose between tts-1 for standard quality or tts-1-hd for higher fidelity. Both models use the same engine and pricing structure, so you can switch seamlessly if your app’s audio requirements change.
Input text limits
Each request supports up to 4096 characters of input text, including spaces and punctuation. For longer scripts, split the text into chunks, generate audio for each, and join the files in your application logic.
Voice and language
Select from 8 voice presets like Aria or Felix. You can optionally specify a language ISO code (e.g., en, de, ja) to ensure correct pronunciation, especially for Latin-script text that isn't English.
- Aria: warm, clear narrator
- Nova: bright, upbeat
- Felix: energetic, promo
Supported audio formats
The VoiceGrid API supports multiple audio formats to suit different deployment needs. You specify the desired format via the response_format parameter in your request. The engine generates the audio file directly in your chosen codec, ensuring compatibility with your specific audio pipeline or player.
MP3 for web
MP3 is the default and most widely supported format for web applications. It offers a good balance between file size and audio quality, making it ideal for playback in browsers or mobile apps.
WAV for quality
Choose WAV if you need uncompressed, high-fidelity audio for local processing or high-quality playback. This format preserves the full audio data without lossy compression, ensuring the best possible sound quality for voice assistants and recording workflows.
FLAC and OPUS
For efficient storage or transmission, FLAC provides lossless compression, while OPUS offers excellent quality at low bitrates. These formats are suitable for advanced use cases where bandwidth efficiency or archival quality is prioritized over universal player compatibility.
Rate limits
VoiceGrid enforces a global limit of 60 requests per minute per API key. This ceiling applies to all endpoints, so plan your batch jobs accordingly. Short phrases may take a few seconds to generate, so under heavy load, requests might queue behind longer syntheses.
60 requests per minute
The standard limit is 60 requests per minute. If you exceed this, the API returns a 429 status code. Plan your parallel requests to stay within this bound for consistent performance.
10 requests initially
New accounts start with a lower limit of 10 requests per minute. This applies immediately upon key creation, even with trial credit. It is designed to prevent accidental spamming before you verify your payment method.
Increase after top-up
To increase your rate limit from the initial 10 to the full 60 requests per minute, top up your balance with USDT (TRC-20). The increase is automatic and credited within minutes after your transfer confirms on the TRON network.

Handling errors
Synthesizing audio is straightforward, but network hiccups happen. Understanding how the API communicates failures helps you build robust integrations that recover gracefully without losing user trust or wasting credits on failed attempts.
Check status codes
The API returns standard HTTP status codes. A 200 OK means your audio file is ready in the response body. Use 400 Bad Request for invalid parameters (like an unknown voice) and 401 Unauthorized if your Bearer token is missing or expired. Always check the response header to confirm success before processing the binary audio data.
- 200: Success, audio data included
- 400: Invalid request parameters
- 401: Invalid or expired API key
- 429: Rate limit exceeded
Handle timeouts
Short phrases generate in seconds, but longer texts (near the 4096-character limit) may take several seconds due to queueing. If your client times out before the response arrives, the request might still be processing. Since failed requests are free, you can safely retry without worrying about duplicate charges.
- Set a generous timeout (e.g., 30s) for long inputs
- Short texts usually respond in under 2 seconds
- Queueing may delay response under load
Retry logic
Implement exponential backoff for transient errors like 429 Too Many Requests or 5xx server errors. Do not retry 400 errors as they indicate a client-side configuration mistake. If a request times out, wait briefly before retrying to avoid thundering herd issues. Remember that only successful generations consume your character balance.
- Retry 429 with exponential backoff
- Retry 5xx errors with delay
- Do not retry 400 errors
- Verify billing status if unsure
Voice presets
Choose from eight distinct voice presets to match your app’s personality. Each voice is engineered for specific use cases, from warm narration to energetic promotions, ensuring your text-to-speech output feels natural and engaging for end users.
Aria and Nova
Aria offers a warm, clear narration style ideal for storytelling or audiobooks. Nova provides a bright, upbeat tone perfect for short announcements or upbeat interfaces.
- Aria: Warm, clear narrator
- Nova: Bright, upbeat
Luna and Sage
Luna delivers a soft, storytelling voice suitable for calm environments. Sage provides a calm, instructional tone, making it excellent for educational content or guided instructions.
- Luna: Soft, storytelling
- Sage: Calm, instructional
Felix and Milo
Felix brings an energetic, promo-focused energy to your audio. Milo offers a friendly, conversational style that works well for chatbots and customer service applications.
- Felix: Energetic, promo
- Milo: Friendly, conversational

Authentication
Secure your VoiceGrid API key by signing up at /get-api-key/. You receive one active key per account, displayed alongside your balance and usage stats.
Bearer token
Include your key in every request header as Authorization: Bearer tts-.... This token authenticates your account and tracks character usage against your balance.
One key per account
Each account maintains a single active API key. If you suspect a leak or need a fresh credential, you can issue a new key from the dashboard.
Regenerate key if needed
Issuing a new key stops the old one instantly. There is no overlap period, so ensure your application updates the token before the old key expires.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Design conversational experiences that feel natural for users interacting with voice assistants and chatbots daily.
23 languages
Any voice speaks any of these languages.
