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.mp3Python (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 | |
|---|---|
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 |
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
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
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
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
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
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
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
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
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
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
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.
23 languages
Any voice speaks any of these languages.
