API Documentation for Text to Speech Integration

By VocalClass editorial team · Updated 2026-11-18

This guide helps teachers and methodologists integrate text-to-speech audio into lesson materials with minimal setup. You will find clear instructions for generating audio files via HTTP requests, managing your API key, and selecting voices that suit educational content. The documentation covers practical steps for Python and JavaScript integration, ensuring you can produce reliable audio for accessibility or classroom use.

We focus on straightforward, transparent processes without unnecessary complexity. You will learn how to handle character limits, understand rate limits, and troubleshoot common issues. All examples use real parameters from our API, so you can copy and paste code directly into your projects. This page is designed for educators who need dependable audio generation for teaching resources.

API Documentation for Text to Speech Integration

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

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

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

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

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

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

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

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

Sound wave illustration for: 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_url to https://api.playt999.com/v1
  • Pass model="tts-1" and voice="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 apiKey with your Bearer token
  • Configure baseURL for VocalClass
  • Request response_format: "mp3" for web compatibility`
SDK Integration

Rate Limits and Queuing

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

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

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

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. Python documentation
  3. OpenAI API reference: create speech
  4. W3C WAI: making audio and video accessible
  5. Creative Commons Attribution 4.0
  6. ISO 639 language codes
  7. LibriTTS-R corpus (OpenSLR 141)
  8. FFmpeg documentation
  9. Tether (USDT)
  10. IETF RFC 7845: Ogg Opus
  11. MDN: Web Speech API
  12. curl documentation

More on this site