Frequently asked questions
How do I get my API key?
Sign up on the /get-api-key/ page using Google or email. Your unique key appears on the dashboard alongside your balance and usage stats. You can issue a new key at any time; the old one stops immediately. Each account is tied to this specific site.
Can I use the OpenAI SDK with this API?
Yes. The request shape matches the OpenAI speech endpoint. Change the base_url to https://api.playt999.com/v1 and use your site’s key. The official OpenAI SDKs work directly without modification, allowing you to integrate quickly into your existing educational tools.
What audio formats are supported?
You can choose from mp3, wav, opus, flac, or pcm. Select the format via the response_format field in your JSON body. MP3 is recommended for general lesson playback due to its balance of quality and file size, while WAV suits high-fidelity needs.
How do I specify the voice in the request?
Include the voice field in your JSON body with one of eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. These voices cover various tones, from warm narration to energetic promo. Use the GET /v1/voices endpoint to see all available options.
What is the maximum character limit per request?
Each request supports up to 4096 characters in the input field. For longer texts, split them into parts of this size and join the resulting audio files. Spaces and punctuation count toward this limit, so plan your lesson scripts accordingly to avoid truncation.
How do I handle rate limits in my code?
The limit is 60 requests per minute per key. Before your first top-up, it is 10 requests per minute. Implement exponential backoff or simple queuing in your code to handle retries gracefully when you approach these limits, ensuring smooth audio generation for your materials.
Can I change the speed of the speech?
Yes, adjust the speed parameter between 0.25 and 4.0. This allows you to slow down complex instructions for students or speed up repetitive content. Set this value in your request body to tailor the audio pacing to your specific educational context.
Does the API support multiple languages in one request?
No, each request handles a single language. If you do not set the language field, the API guesses it from the script. For non-English Latin text, explicitly set the language code to ensure accurate pronunciation and avoid misinterpretation by the synthesis engine.
What happens if I exceed the rate limit?
Requests are processed sequentially, so you may wait in a queue under load. If synthesis fails, the charge is returned in full. Exceeding the per-minute limit typically results in temporary delays or HTTP 429 errors, which your code should handle with retries.
How do I detect which language the API used?
If you do not provide the language field, the API guesses it from the script. Latin script defaults to English. To know exactly which language was used, always specify the ISO code in your request.
Can I generate audio in MP3 format?
Yes, MP3 is a supported response format. You can also choose WAV, OPUS, FLAC, or PCM. Set the response_format field to 'mp3' in your JSON body. This format is widely compatible with educational platforms and learning management systems used in schools.
Is there a limit to the number of requests per day?
There is no daily limit on the number of requests. The constraint is per minute: 60 requests per minute after top-up, or 10 before. You can generate as much audio as your balance allows, limited only by these per-minute throughput caps.
How do I cancel a subscription if I have one?
We do not offer subscriptions. You pay via USDT top-up, and your balance does not expire. There are no monthly plans or seats to cancel. Simply stop topping up when your credit runs out, and your access ends naturally without further action.
What is the base URL for the API?
The base URL is https://api.playt999.com/v1. Use this for all endpoints, including POST for speech generation and GET for voices. If using the OpenAI SDK, set this as your base_url to ensure requests are routed correctly to our infrastructure.
First request
curl
curl https://api.playt999.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.playt999.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.playt999.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 |
Authentication
To use the API, you need a key from /get-api-key/. Create an account with Google or email, then find your key on the dashboard. Keep this key secure, as it controls your billing and usage.
Generating Your API Key
Visit the registration page and sign up using your Google account or email. Once logged in, your dashboard displays your unique API key alongside your current balance and usage statistics. This key is the only credential needed for all requests.
Using Bearer Tokens
Include your key in every request header using the format: Authorization: Bearer tts-.... The API validates this token before processing your text. If the token is missing or invalid, the server returns a 401 error immediately.
Rotating Keys
Generate a new key from your dashboard at any time. The previous key stops working instantly, ensuring that lost credentials cannot be used to access your account. This is useful if you share keys with students or colleagues for classroom projects.
Endpoint Overview
The API provides three primary endpoints for managing speech synthesis. The Speech Generation endpoint processes your text into audio files. The Voices Listing and Models endpoints allow you to query available options programmatically.
Speech Generation Endpoint
Send a POST request to https://api.playt999.com/v1/audio/speech with your text and voice settings. The API returns an audio file in your chosen format, ready for download or immediate playback in lesson materials.
- Endpoint: POST https://api.playt999.com/v1/audio/speech
- Returns: Audio file (mp3, wav, opus, flac, pcm)
Voices Listing Endpoint
Use GET /v1/voices to retrieve the full list of 8 voice presets, supported languages, and available audio formats. This helps you select the right tone for your educational content without guessing.
- Endpoint: GET /v1/voices
- Returns: Voice IDs, languages, and format options
Models Endpoint
Call GET /v1/models to verify the available model versions. Currently, tts-1 and tts-1-hd are supported, both using the same engine and pricing structure for consistent quality across your library.
- Endpoint: GET /v1/models
- Returns: Available model IDs and versions
Request Parameters
The API accepts plain text input for synthesis, with a strict limit of 4096 characters per request. Spaces and punctuation count toward this total, so plan your lesson segments accordingly. For texts exceeding this length, split them into smaller parts and join the resulting audio files manually.
Select one of eight preset voices to match your teaching style. Each voice has a distinct tone, from warm narrators to energetic presenters. You can also specify an optional ISO language code to ensure accurate pronunciation, especially for non-English Latin script texts where the default behavior guesses English.
Input Text Field
Send the text to synthesize in the input field of the JSON body. The maximum length is 4096 characters. If your lesson material is longer, split it into chunks and concatenate the audio outputs.
Voice Selection
Choose from eight distinct voices tailored for different educational contexts. Use aria for clear narration, nova for upbeat content, or atlas for neutral news-style reading. Each voice supports all 23 available languages.
- aria: Warm, clear narrator
- nova: Bright, upbeat
- luna: Soft, storytelling
- sage: Calm, instructional
- felix: Energetic, promo
- milo: Friendly, conversational
- atlas: Neutral, news
- orion: Deep, documentary
Response Format Options
Specify the output format using the response_format field. Supported formats include mp3, wav, opus, flac, and pcm. Choose mp3 for small file sizes or wav for high-quality uncompressed audio suitable for classroom playback.
Adjust the playback speed with the speed parameter, ranging from 0.25 to 4.0. This allows you to slow down complex instructions or speed up simple reviews, ensuring the audio fits your lesson pacing.
- mp3: Compressed, small size
- wav: Uncompressed, high quality
- opus: Efficient compression
- flac: Lossless compression
- pcm: Raw audio data
Response Handling
Upon successful synthesis, the API returns the audio file directly in the response body. You can save this file locally or play it in your lesson players. The format matches your requested response_format, ensuring compatibility with standard educational tools.
Audio File Delivery
The audio data is returned immediately upon completion. For long texts split into parts, you receive multiple responses that you must join sequentially. Each file is tagged with a synthetic watermark to identify it as generated content.
- Formats: mp3, wav, opus, flac, pcm
- Files are not stored after delivery
- Inaudible watermark marks synthetic speech
Status Codes
A 200 OK response indicates successful generation. A 400 error means invalid parameters, such as text exceeding 4096 characters or an unknown voice. A 429 error signals you have exceeded the 60 requests per minute limit.
Error Messages
If synthesis fails, the charge is returned in full. The response body includes a clear message explaining the issue, such as invalid input or temporary service unavailability. Check your text length and voice selection before retrying.
SDK Integration
The API mirrors the OpenAI speech endpoint structure, allowing you to use official SDKs by simply changing the base URL. This means your existing code can connect to VocalClass with minimal adjustments, making integration straightforward for educational software projects.
You can generate audio files directly in Python or JavaScript using the OpenAI SDK or plain HTTP, ensuring reliable delivery for lesson materials and accessibility resources.
OpenAI SDK Compatibility
By setting the base URL to https://api.playt999.com/v1, the official OpenAI SDKs recognize our endpoints. You pass your API key as a bearer token, and the library handles the request shape automatically.
This compatibility extends to both tts-1 and tts-1-hd models, ensuring consistent behavior whether you are generating short phrases or longer lesson texts.
Python Example
Use the openai Python package to generate audio. Set the base URL to the VocalClass API endpoint and provide your API key.
The code sends the text, voice, and format parameters, returning the audio file for immediate playback or storage in your learning management system.
- Install via pip:
pip install openai - Set
base_urltohttps://api.playt999.com/v1 - Pass
model="tts-1"andvoice="nova"
JavaScript Example
In JavaScript, initialize the OpenAI client with the custom base URL. Pass the text and voice configuration to the audio.speech.create method.
This approach works in both browser and Node.js environments, allowing you to embed audio directly into web-based educational tools.
- Set
apiKeywith your Bearer token - Configure
baseURLfor VocalClass - Request
response_format: "mp3"for web compatibility`

Rate Limits and Queuing
This API limits usage to 60 requests per minute per key. New accounts without a top-up start with a stricter limit of 10 requests per minute. This ensures fair usage while you prepare your lesson materials.
60 Requests Per Minute
You may send up to 60 API calls each minute using your active key. If you have just created your account without adding funds, this limit drops to 10 requests per minute. Once you top up, the standard 60 rps limit applies immediately.
Queue Behavior
Requests are processed sequentially. If you exceed the per-minute limit, additional requests wait in a queue until slots become available. This means that during high load, synthesis may take slightly longer than usual. You do not need to manually retry; the API handles the ordering.
Speed of Generation
Long texts generate at roughly real-time speed, approximately 25 characters of text per second of audio. Short phrases may take a few seconds to process due to initialization overhead. For very long lessons, splitting the text into parts under 4096 characters is recommended for consistent delivery.
Voice and Language Settings
VocalClass provides eight distinct voice presets optimized for clear educational delivery. Female voices include Aria (warm narrator), Nova (bright), Luna (soft storytelling), and Sage (calm instruction). Male options offer Felix (energetic promo), Milo (conversational), Atlas (neutral news), and Orion (deep documentary). Each voice is based on licensed recordings from LibriTTS-R (CC BY 4.0) and LibriVox public-domain audiobook readings.
Available Voices List
Select a voice by its name in the voice parameter. All eight voices support the full range of 23 languages, allowing you to maintain consistent audio style across different lesson languages without switching voice models.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
ISO Language Codes
Specify the target language using its ISO code (e.g., de, fr, ja) in the language field. This ensures correct pronunciation for your students. Supported languages include Arabic, Chinese, English, German, Spanish, and 18 others.
Default Language Behavior
If you omit the language field, the system guesses the language from the text script. Latin script defaults to English. For non-English Latin text (like French or German), always set the language parameter to avoid incorrect English pronunciation.
Troubleshooting
Even with straightforward integration, educators may encounter predictable hurdles when generating audio for lesson materials. Understanding how the API handles limits and errors helps you adjust your workflow without unnecessary delays.
Common Errors
A 401 error indicates an invalid or expired API key. Ensure your request includes the correct Authorization: Bearer header. If you rotated your key recently, verify the old one is no longer in use.
Character Limit Issues
Each request accepts a maximum of 4096 characters. If your lesson text exceeds this, split it into smaller parts before sending. The API does not automatically handle long texts; you must join the resulting audio files.
Network Timeouts
Requests are processed sequentially. Under load, a request may wait in a queue, potentially causing timeouts if you expect instant results. For large batches, consider spacing out requests or monitoring the rate limit of 60 requests per minute.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Effective teaching strategies empower educators to adapt dynamically to diverse classroom needs and foster meaningful student engagement.
23 languages
Any voice speaks any of these languages.
