Build Audio Apps with the VoiceGrid TTS API

By VoiceGrid editorial team · Updated 2026-11-18

This guide shows indie developers how to integrate high-quality text-to-speech into chatbots and voice assistants using the VoiceGrid API. You will learn to send text via simple HTTP requests and receive audio files (processing takes a few seconds for short phrases, roughly real-time for long texts). The documentation covers everything from your first curl command to handling rate limits and errors with practical code examples.

We use the same request shape as the OpenAI speech endpoint, so existing SDKs work with a simple base URL change. Whether you need MP3 for web players or WAV for high-fidelity processing, this page provides the exact parameters, voice presets, and authentication details you need to build reliable audio features without infrastructure headaches.

Build Audio Apps with the VoiceGrid TTS API

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

Python (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
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

Quickstart with curl

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

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

Using the OpenAI SDK

Request parameters

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

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

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

Rate limits

Handling errors

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

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

Authentication

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

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. W3C WAI: making audio and video accessible
  3. Node.js documentation
  4. LibriTTS-R corpus (OpenSLR 141)
  5. FFmpeg documentation
  6. ISO 639 language codes
  7. TRON developer hub: TRC-20
  8. curl documentation
  9. Tether (USDT)
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. openai-python on GitHub
  12. IETF RFC 7845: Ogg Opus

More on this site