Complete Reference Guide for Voxable TTS Integration

By Voxable editorial team · Updated 2026-11-18

This documentation helps indie developers and no-code creators integrate natural-sounding text-to-speech into their projects. We provide a simple API that works like the OpenAI speech endpoint, allowing you to generate audio files with just a few lines of code. Whether you are building a mobile app, a web tool, or an automated voice system, you can get started quickly with clear examples and straightforward parameters.

You will find details on authentication, supported voices, and available audio formats like MP3 and WAV. Learn how to handle rate limits, manage your API key, and understand pricing based on character count. All features are described with concrete numbers and real-world constraints, so you know exactly what to expect when sending text and receiving audio.

Complete Reference Guide for Voxable TTS Integration

Frequently asked questions

Is the API compatible with OpenAI SDKs?

Yes. Our API uses the same request shape as the OpenAI speech endpoint, so official OpenAI SDKs work by changing the base URL to https://api.playk999.com/v1. This lets you integrate our text-to-speech service into your projects with minimal code changes, without needing a custom library.

How do I change the base URL?

Update your SDK configuration to point to https://api.playk999.com/v1. Use this base URL for all requests. Ensure your Authorization header includes your Bearer token starting with 'tts-'. This single change directs all calls to our infrastructure while maintaining compatibility with standard OpenAI SDK structures.

What is the maximum input length?

Each request supports up to 4096 characters of input text. If your text exceeds this limit, you must split it into smaller parts. Generate audio for each part separately, then join the resulting audio files to create the final output. Spaces and punctuation count toward the limit.

Can I stream the audio?

No. We do not offer streaming, WebSocket, or real-time partial audio. The API returns the complete audio file in the response after synthesis finishes. For long texts, split your input into parts of up to 4,096 characters and join the resulting files manually after each request completes successfully.

How do I handle rate limits?

You are limited to 60 requests per minute per key. New accounts start with 10 requests per minute until the first top-up. If you exceed the limit, requests may queue or fail. Monitor your usage via the dashboard and implement retry logic with exponential backoff for your applications.

What formats are supported?

You can choose from mp3, wav, opus, flac, or pcm. All formats use the same synthesis engine and duration, but quality differs: wav and flac are lossless, while mp3 and opus are compressed. Choose based on your needs for file size versus fidelity. The voice remains identical across all options.

Can I specify a language explicitly?

Yes. You can set the 'language' field to an ISO code like 'en', 'es', or 'fr'. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accurate pronunciation, especially for non-English texts using Latin characters.

Are there JSON or SSML responses?

No. We do not support SSML, phoneme dictionaries, or custom pronunciation lexicons. The API returns the audio file in your requested format (mp3, wav, opus, flac, or pcm) as the response body. While we keep request metadata like time and status for billing purposes, this data is not included in the primary response. You should use standard HTTP status codes to handle errors during integration.

How do I rotate my API key?

Issue a new key from your account dashboard at any time. The new key becomes active immediately, and the old one stops working at once. This ensures seamless rotation without downtime. You can generate a new key as often as needed to maintain security for your applications.

What happens if the server is busy?

Requests are processed sequentially. Under load, your request may wait in a queue. Typical speed is roughly real-time, but short phrases take a few seconds. If the server is busy, you will experience delays before the audio is generated. Be patient and implement appropriate timeouts in your code.

Is there a webhook for status?

No. We do not provide webhooks for status updates or completion notifications. You must poll the API or wait for the synchronous response. Request metadata is kept for billing purposes. Monitor your usage and balance directly through the dashboard or by checking your account details.

Can I use multiple voices in one request?

No. Each request supports only one voice preset. To use different voices, you must send separate requests for each segment. Generate the audio for each voice individually, then join the files. You can choose from eight presets like Aria, Nova, Felix, or Atlas per request.

How do I debug a failed request?

Check the HTTP status code and response body for error details. Failed requests are free, and charges are returned in full if synthesis fails. Ensure your text is under 4096 characters and your API key is valid. Review the documentation for common issues like invalid voice names or format errors.

Do I need to install any libraries?

No. Use the official OpenAI SDKs or plain HTTP. No custom libraries or mobile SDKs are required. Just set the base URL to https://api.playk999.com/v1 and send standard JSON payloads. This simplicity lets indie developers and no-code creators integrate quickly without managing extra dependencies or complex setup steps.

First request

curl

curl https://api.playk999.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.playk999.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.playk999.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

Authentication

Sound wave illustration for: Authentication

Access the Voxable API using a Bearer token in your Authorization header. This key authenticates your requests and tracks your usage against your account balance.

Bearer Token

Include your API key in every request using the header Authorization: Bearer tts-.... This simple method works with standard HTTP libraries and the official OpenAI SDK by adjusting the base URL.

One Active Key

Your account maintains only one active key at a time. If you issue a new key, the previous one becomes invalid immediately, ensuring clear security boundaries.

Key Rotation

Rotate your key anytime via the dashboard. The old key stops working instantly, while the new one becomes active for your next requests. This is useful if you suspect exposure.

Speech Endpoint

Sound wave illustration for: Speech Endpoint

To generate audio, send a POST request to https://api.playk999.com/v1/audio/speech. The endpoint accepts a JSON body containing your configuration and input text. You can use the official OpenAI SDKs by updating the base_url to https://api.playk999.com/v1 and providing your API key.

The generated audio is returned in the response and not stored on our servers. Ensure your application handles the binary or base64 data immediately upon receipt to save the file locally or stream it to your users.

POST Request

Send a POST request to https://api.playk999.com/v1/audio/speech. Include your API key in the Authorization header as Bearer tts-.... The request must include a JSON body with the model, input, voice, and response_format fields. The input text must not exceed 4096 characters.

  • Endpoint: POST https://api.playk999.com/v1/audio/speech
  • Header: Authorization: Bearer tts-...
  • Body: JSON with model, input, voice, response_format

JSON Body

The request body is a standard JSON object. Use tts-1 or tts-1-hd for the model. The input field accepts your text string. Choose a voice from the 8 available presets. Set response_format to one of mp3, wav, opus, flac, or pcm. You may optionally specify a language ISO code or speed (0.25–4.0).

  • model: "tts-1" or "tts-1-hd"
  • input: String (max 4096 chars)
  • voice: One of 8 presets (e.g., "aria")
  • response_format: "mp3", "wav", "opus", "flac", or "pcm"
  • speed: Number (0.25–4.0)
  • language: Optional ISO code

Response Format

A successful response returns the audio data directly. The content type matches your requested response_format. If the synthesis fails, you will receive an error JSON object with details. Failed requests are free, and any charges are returned in full.

  • Success: Audio binary or base64 string
  • Error: JSON object with error details
  • Content-Type matches response_format
Speech Endpoint

Parameters

Sound wave illustration for: Parameters

The API uses two model options, "tts-1" and "tts-1-hd," which share the same underlying engine and price. You can select the model that best fits your workflow without worrying about unexpected cost changes or significant quality differences between the two choices.

Model Selection

Both models accept the same input parameters and deliver consistent results. Choose based on your preference for file naming conventions or specific SDK integrations, as the synthesis logic remains identical.

Input Text

Send your script via the input field. The API accepts up to 4096 characters per request, including spaces and punctuation. For longer texts, split your content into chunks and join the resulting audio files.

Each character counts toward your usage. Ensure your text is within the limit to avoid truncation or errors during synthesis.

Voice Selection

Choose from eight distinct voice presets, each optimized for different tones. Female voices include Aria (warm narrator), Nova (bright), Luna (soft storytelling), and Sage (calm instructional). Male options are Felix (energetic), Milo (friendly), Atlas (neutral news), and Orion (deep documentary).

Any voice can speak all 23 supported languages. If the language field is omitted, the system guesses the language from the script, defaulting to English for Latin text.

  • Aria: Warm, clear narrator
  • Nova: Bright, upbeat
  • Luna: Soft, storytelling
  • Sage: Calm, instructional
  • Felix: Energetic, promo
  • Milo: Friendly, conversational

Audio Formats

Sound wave illustration for: Audio Formats

The response_format parameter lets you choose how the generated audio is encoded. You can select from five standard formats to suit your project's needs, balancing file size, quality, and compatibility.

MP3

MP3 is the most widely supported format for web playback and mobile apps. It offers a good balance between file size and audio quality, making it ideal for general use cases.

WAV

WAV provides uncompressed, high-quality audio. This format is perfect for professional editing or when you need lossless fidelity without any compression artifacts.

OPUS

OPUS is a highly efficient codec that delivers excellent quality at low bitrates. It is excellent for real-time streaming or bandwidth-constrained environments.

FLAC

FLAC offers lossless compression. It preserves all original audio data while reducing file size, making it suitable for archiving or high-fidelity distribution.

PCM

PCM is an uncompressed, raw audio format. It provides the purest data stream, useful for direct processing or when you want to handle compression yourself.

Speed and Language

Sound wave illustration for: Speed and Language

Adjust speech pacing with the speed parameter, accepting values between 0.25 and 4.0. This allows you to slow down complex technical instructions or accelerate casual updates. Note that generation speed remains roughly real-time, processing approximately 25 characters per second, so higher speeds may still queue behind other requests during peak usage.

Speed Range 0.25-4.0

Set speed as a decimal value in your request body. Values below 1.0 slow the voice, while values above 1.0 accelerate it. The API handles these adjustments seamlessly without affecting audio quality or character counting.

Optional Language Code

Specify the language field using an ISO 639-1 code (e.g., en, de, ja) to ensure correct pronunciation. This is especially useful when your text uses Latin script but is not English, preventing the system from defaulting to English pronunciation.

  • Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.

Auto-Detection

If you omit the language field, the API guesses the language based on the text script. Latin script defaults to English. For non-English Latin text, always set the language code to avoid mispronunciation.

Speed and Language

Rate Limits

Sound wave illustration for: Rate Limits

The API enforces a strict rate limit of 60 requests per minute for each active API key. This limit ensures fair usage across the network. If you exceed this threshold, requests will be rejected until the window resets.

60 Requests Per Minute

Once you top up with USDT on the TRON network (TRC-20), your limit increases to the full 60 requests per minute immediately. This applies to your single active key.

10 Requests Before Top-Up

Before your first top-up, the limit is 10 requests per minute. This allows you to test the API with your free trial credit. After topping up, the limit scales up instantly.

Queue Processing

Requests are processed one after another. Under load, a request may wait in a queue. This ensures orderly generation without dropping inputs.

Error Handling

Sound wave illustration for: Error Handling

Our API handles common issues gracefully so you can focus on building. When a request fails, you are not charged, and any prepaid balance is returned in full immediately. This ensures your credits are safe even if the synthesis engine encounters a temporary hiccup.

Failed Requests

If synthesis fails, the charge is returned in full. You do not lose credits for unsuccessful attempts, making it safe to retry without worrying about your balance.

Character Limit

Each request accepts up to 4096 characters. If your text is longer, split it into chunks and join the resulting audio files. Spaces and punctuation count toward this limit.

Invalid Voice

Use only the 8 available presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Providing an unknown voice name will return an error without charging your account.

Error Handling

Quick Start with cURL

Sound wave illustration for: Quick Start with cURL

Get started instantly with a single command. This example sends a short text to the API and receives an audio file. You can run this directly in your terminal to verify your key works before integrating it into your no-code workflows.

The response contains the raw audio bytes. You can save this output directly to a file on your computer for immediate playback or further processing.

Command Example

Run the following command, replacing YOUR_API_KEY with your actual key from the dashboard:

```bash curl -X POST https://api.playk999.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}' \ -o output.mp3 ```

Response Data

On success, the API returns the audio binary data directly in the response body. There is no JSON wrapper for the audio itself. If the request fails (e.g., invalid key or rate limit), you will receive a JSON error object with a status code and message explaining the issue.

Audio Download

The -o output.mp3 flag in the cURL command saves the binary response into a file named output.mp3. You can then play this file in any media player or embed it in your project. Remember that generated audio carries an inaudible watermark marking it as synthetic speech.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Indie developers use no-code tools to bring their unique creative game visions to life effortlessly.

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. OpenAI API reference: create speech
  3. TRON developer hub: TRC-20
  4. Creative Commons Attribution 4.0
  5. W3C WAI: making audio and video accessible
  6. LibriVox public-domain audiobooks
  7. openai-python on GitHub
  8. Python documentation
  9. openai-node on GitHub
  10. ISO 639 language codes
  11. LibriTTS-R corpus (OpenSLR 141)
  12. MDN: Web Speech API

More on this site