Text to Speech API Integration Guide for Developers

By VoxClass editorial team · Updated 2026-11-18

This documentation provides a practical integration guide for developers building educational audio tools. It covers essential endpoints, parameter configurations, and workflow patterns for converting textbooks and lesson plans into synthetic speech. The guide assumes familiarity with standard HTTP requests and JSON structures.

You will learn how to authenticate, generate audio files in various formats, and manage rate limits effectively. The content is tailored for engineers implementing TTS features for schools and teachers, ensuring accurate character counting and proper handling of long-form educational content.

Text to Speech API Integration Guide for Developers

Frequently asked questions

How do I get an API key?

Navigate to /get-api-key/ on play4447.com and sign up using Google or an email and password. Your account page displays your active API key, balance, and usage statistics. Each account holds one active key, which can be regenerated at any time via the same interface.

What is the base URL for the API?

The API base URL is https://api.play4447.com/v1. Use this endpoint for all requests, including POST /v1/audio/speech for generation, GET /v1/voices for available options, and GET /v1/models for model information. Ensure your Authorization header uses the Bearer token format.

Which SDKs are supported?

We do not provide an official proprietary SDK. However, the request shape matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.play4447.com/v1 and providing your site-specific key in the Authorization header.

How do I set the voice parameter?

Include one of the eight preset voices in your request body: aria, nova, luna, sage, felix, milo, atlas, or orion. These voices are based on licensed recordings from LibriTTS-R and LibriVox. You can view all available voices and their details via the GET /v1/voices endpoint.

What is the character limit per request?

Each API request supports a maximum of 4096 characters in the input field. Spaces and punctuation count toward this limit. If your text exceeds this length, you must split it into smaller parts, generate audio for each, and join the resulting audio files.

How do I handle errors?

If synthesis fails, the charge is returned in full, making the request free. Failed requests do not incur costs. You should check the response status and retry if necessary, keeping in mind that requests are processed sequentially and may queue under load.

What are the rate limits?

You are limited to 60 requests per minute per API key. Before your first top-up, this limit is reduced to 10 requests per minute. These limits apply to your active key and are enforced to ensure stable service during peak usage periods.

How do I process long texts?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate POST request to /v1/audio/speech. Once you receive the audio file for each part, join them sequentially to create the complete audio file for your educational material.

Is SSML supported?

No, SSML is not supported. The API accepts plain text input only. It does not offer phoneme dictionaries, custom pronunciation lexicons, or emotion tags. You must rely on the natural prosody of the selected voice presets for your text-to-speech generation.

Can I stream audio in real-time?

No streaming or WebSocket support is available. The API returns the complete audio file in the response after generation. Requests are processed sequentially, so longer texts may take time proportional to their length, roughly real-time speed, without partial audio delivery.

How do I revoke an API key?

Generate a new API key via the /get-api-key/ page. When you issue a new key, the previous one stops working immediately. This effectively revokes access for the old key without needing a separate deactivation step or waiting for a timeout period.

What happens if the request fails?

If synthesis fails, the charge is returned in full. You are not billed for failed requests. This ensures that errors in processing do not impact your balance, allowing you to retry the request or adjust parameters without financial penalty.

Is there a WebSocket endpoint?

No, there is no WebSocket endpoint for real-time streaming. All interactions are standard HTTP requests. You send a POST request and receive the generated audio file in the response body, supporting formats like mp3, wav, opus, flac, and pcm.

How do I specify the language?

Include the optional 'language' field with an ISO code in your request body. If omitted, the system guesses the language based on the script, defaulting to English for Latin text. Explicitly setting the language ensures accurate pronunciation for non-English Latin-script content.

First request

curl

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

Getting Your API Key

Sound wave illustration for: Getting Your API Key

VoxClass provides a straightforward path to generating audio for educational content. Access your API credentials by visiting the /get-api-key/ page on play4447.com. You can create an account using Google or a standard email and password combination.

Once registered, your unique API key is displayed immediately on the dashboard. This key authenticates your requests to the voice engine. If you distribute access to multiple teachers, you can generate new keys at any time.

Sign up on the site

Sign up on the site

Navigate to the registration page to create your account. You may sign in using Google for quick access or provide an email address and password. Accounts are specific to this site, ensuring isolated credentials for your educational projects.

Upon signing in with Google, you receive a free trial credit of $0.50, valid for seven days. This allows you to test the API with approximately 50,000 characters before committing to a top-up. Email-based accounts do not receive this trial credit.

Retrieve your key from the dashboard

Retrieve your key from the dashboard

After logging in, the dashboard displays your active API key, current balance, and usage statistics. The key format begins with "tts-" and is required for authentication. You can copy this value directly into your integration scripts or code editors.

The dashboard also shows your remaining character count and recent activity. This transparency helps educators track consumption across different lesson plans or textbook conversions without needing external billing tools.

Revoke and replace keys as needed

Revoke and replace keys as needed

Security is managed by issuing fresh keys rather than revoking specific ones individually. When you generate a new key from the dashboard, the previous key stops working immediately. This ensures that only active credentials can access your account.

This model simplifies access management for schools or departments. If a teacher’s key is compromised or no longer needed, simply generate a new one. The old key becomes invalid instantly, preventing unauthorized usage.

Making Your First Request

Sound wave illustration for: Making Your First Request

To generate audio, send a POST request to https://api.play4447.com/v1/audio/speech. The endpoint accepts a JSON body containing the text, voice selection, and output format.

Use the provided curl example to test immediately. Ensure your API key is correctly formatted in the header to avoid authentication errors.

Use curl for quick testing

Run this command in your terminal to verify connectivity. Replace YOUR_API_KEY with your actual key and Your text here with the content you wish to convert. The response will be the audio file in the specified format.

  • Verify your key is active
  • Check response format matches your need

Set the Authorization header

Include the header Authorization: Bearer tts-your_key_here in every request. The key is issued upon account creation and remains valid until you revoke it.

  • Format: Bearer tts-...
  • One key per account

Send text in the JSON body

Structure your payload with model, input, and voice. The input field accepts up to 4096 characters. Spaces and punctuation count toward this limit.

  • Model: tts-1 or tts-1-hd
  • Max 4096 characters per request

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

To integrate VoxClass, modify the OpenAI SDK's base URL to https://api.play4447.com/v1 while keeping your existing code structure. This allows you to use the official OpenAI libraries with our TTS endpoint without rewriting client logic. Pass your API key via the Authorization header as standard.

Change base_url to our API

Update the base URL configuration in your SDK client to point to https://api.play4447.com/v1. This directs requests to our speech endpoint while maintaining compatibility with standard OpenAI client methods.

Use official OpenAI SDKs

You can use any official OpenAI SDK (Python, Node.js, etc.) by simply redirecting the base URL. No custom client library is required, reducing setup time for your development team.

Standard request shape

The request body follows the standard OpenAI speech format. Include your model (tts-1 or tts-1-hd), input text, selected voice, and optional speed or language parameters in the JSON payload.

Request Parameters Explained

Sound wave illustration for: Request Parameters Explained

The API accepts a concise JSON body to generate audio. You must specify the model, voice, and input text. All parameters are straightforward, ensuring quick integration for developers building educational tools.

Model: tts-1 or tts-1-hd

Both models use the same engine and pricing at $10 per 1 million characters. Choose "tts-1" for standard generation or "tts-1-hd" if you prefer the high-definition variant, which maintains identical cost and quality characteristics.

Voice: choose from 8 presets

Select from eight licensed voices based on LibriTTS-R recordings. These presets include female voices like Aria and Nova, and male voices like Felix and Atlas, all designed for clear narration of textbooks and lesson plans.

  • Aria: warm, clear narrator
  • Felix: energetic, promo
  • Luna: soft, storytelling
  • Milo: friendly, conversational

Speed: 0.25 to 4.0

Adjust the playback speed between 0.25 and 4.0 to suit different learning paces. This allows educators to slow down complex material or speed up routine reviews without re-generating the audio file.

Supported Response Formats

Sound wave illustration for: Supported Response Formats

The response_format parameter determines the audio container returned by the API. Selecting the appropriate format ensures compatibility with your educational platforms and playback devices. MP3 remains the standard for broad web compatibility, while WAV offers uncompressed quality for local processing.

Other formats cater to specific technical needs. FLAC provides lossless compression, OPUS offers high efficiency, and PCM delivers raw audio data for immediate analysis or further processing by educational software.

MP3 for web compatibility

MP3 is the recommended default for most educational use cases. It provides a balance of file size and quality, ensuring smooth playback in standard web browsers and mobile devices without requiring additional plugins.

  • Widely supported by HTML5 audio players
  • Compact file size for faster loading
  • Suitable for classroom presentations and online courses

WAV for high quality

WAV output delivers uncompressed audio. This format is ideal when you need the highest fidelity for archival purposes or when integrating with local audio editing software used by methodologists.

  • Uncompressed audio data
  • Ideal for local processing
  • Higher file size than MP3

FLAC, OPUS, and PCM options

FLAC offers lossless compression, reducing file size without quality loss. OPUS is optimized for low-bandwidth. PCM returns raw audio bytes, useful for real-time analysis or custom audio pipelines in learning management systems.

  • FLAC: Lossless compression
  • OPUS: Efficient compression
  • PCM: Raw audio bytes for analysis

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

Rate limits protect service stability during peak usage. Each API key is capped at 60 requests per minute once your account is fully funded. This limit applies uniformly across all endpoints, ensuring consistent performance for classroom audio generation workflows.

60 requests per minute per key

The standard limit allows 60 requests per minute per key. This capacity supports moderate batch processing of lesson plans or textbook excerpts without requiring complex queue management for most educational use cases.

10 requests per minute initially

New accounts start with a reduced limit of 10 requests per minute. This lower threshold helps manage server load before you verify your payment method. You can test the API and generate sample audio files within these constraints.

Limits reset after top-up

Rate limits automatically increase to the full 60 requests per minute once a minimum $5 top-up is processed via USDT (TRC-20). The increase occurs within minutes of transfer confirmation, allowing immediate scaling of your audio generation capacity.

Handling Errors

Sound wave illustration for: Handling Errors

API errors are returned as JSON objects with an HTTP status code indicating the failure type. Failed synthesis requests are free, and any charges are fully refunded if the service cannot generate audio from your input.

Check HTTP status codes

Use standard HTTP status codes to diagnose issues. A 401 error indicates an invalid or revoked API key, while a 429 error signals that you have exceeded the rate limit of 60 requests per minute.

  • 400: Bad Request (invalid parameters)
  • 401: Unauthorized (bad key)
  • 429: Too Many Requests

Review error messages in JSON

The response body contains a JSON object detailing the error. Review the message field to understand why a specific request failed, such as exceeding the 4096 character limit per request.

Retry failed requests

Implement retry logic for transient errors like 429. Since failed requests incur no cost, you can safely retry without worrying about billing discrepancies, ensuring your audio generation pipeline remains robust.

Processing Long Texts

Sound wave illustration for: Processing Long Texts

Teachers often need to convert full lesson plans or short textbook chapters, which frequently exceed the 4,096-character limit per request. To handle this, your application must split the input text into smaller segments before sending them to the API.

Split text into 4096 char chunks

Divide your source material into blocks of up to 4,096 characters. Each character, including spaces and punctuation, counts toward this limit. This ensures every request stays within the single-request boundary defined by the API specifications.

Join audio files sequentially

The API returns each segment as a separate audio file. Your client code must download these files in order and concatenate them into a single continuous audio track. This preserves the narrative flow for students listening to the compiled lesson.

Manage character limits

Monitor your character usage against your balance. Since each chunk consumes credits independently, splitting long texts increases the number of API calls required. Ensure your script handles the sequential processing efficiently to avoid unnecessary delays during generation.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Empowering educators with adaptable frameworks to nurture critical thinking and foster genuine curiosity in every learner.

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. LibriVox public-domain audiobooks
  3. Python documentation
  4. W3C WAI: making audio and video accessible
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. LibriTTS-R corpus (OpenSLR 141)
  7. TRON developer hub: TRC-20
  8. openai-node on GitHub
  9. Tether (USDT)
  10. FFmpeg documentation
  11. Node.js documentation
  12. curl documentation

More on this site