Cloud TTS API Documentation for Developers

By Web Speech Logic editorial team · Updated 2026-11-18

This guide shows SaaS teams how to integrate our cloud text-to-speech API using the official OpenAI SDK. By simply adjusting the base_url to https://api.playtop99.com/v1, you can leverage familiar SDK methods for reliable audio generation in your notifications and interfaces. We cover authentication, request parameters, and rate limits to help you scale efficiently without managing infrastructure.

You will learn to manage API keys, handle rate limits, and format requests for various audio outputs like MP3 and WAV. The documentation also details voice presets, speed controls, and error handling specific to high-volume deployments. This resource is designed for developers who need a straightforward, cost-effective alternative to browser-based speech APIs for large-scale applications.

Cloud TTS API Documentation for Developers

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.playtop99.com/v1. You configure your client to use this endpoint for all requests, including speech synthesis and voice listing. This ensures your application connects directly to the correct infrastructure for text-to-speech processing.

Does it work with the official OpenAI SDK?

Yes, the endpoint shape matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.playtop99.com/v1 and providing your site-specific key. This allows seamless integration without requiring a custom client library.

What is the maximum input length?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer texts, you must split the content into chunks of 4096 characters or less and join the resulting audio files manually.

Can I send audio in WAV format?

Yes, WAV is a supported response format. You specify this by setting the response_format field to 'wav' in your request body. Other supported formats include mp3, opus, flac, and pcm, allowing flexibility based on your application’s audio processing needs.

Is FLAC supported?

Yes, FLAC is supported as a response format. Set the response_format field to 'flac' in your JSON request body. This provides lossless audio quality, suitable for archival or high-fidelity playback scenarios within your SaaS notification or interface systems.

How do I set the speed?

Use the speed parameter in your request body, accepting values between 0.25 and 4.0. Adjusting this value allows you to control the playback rate of the generated synthetic speech to fit your interface context.

What happens if the rate limit is exceeded?

The limit is 60 requests per minute per key (10 before top-up). Exceeding this may cause requests to queue or fail. Failed requests are free, so you are not charged for audio that does not generate successfully due to limits or errors.

Do I need to install a specific SDK?

No, you do not need a specific SDK for this service. You can use the official OpenAI SDK or plain HTTP requests. The API follows standard REST conventions, making it compatible with any HTTP client capable of sending JSON and receiving binary audio.

Is the response JSON or binary?

The response is binary audio data, not JSON. The JSON request body defines parameters like model, voice, and format. The actual output is the audio file itself, streamed directly in the response body according to the specified response_format, such as mp3 or wav.

Can I request multiple voices at once?

No, each request generates audio for a single voice. You specify one voice from the eight available presets in the voice field. To use different voices, you must send separate requests for each voice and join the resulting audio files.

What is the model name?

The model name is either 'tts-1' or 'tts-1-hd'. Both use the same engine and price. You can choose either based on your quality preference, as the underlying synthesis technology remains identical between the two model options for standard and high-definition output.

Are there any required headers?

You must include the Authorization header with your Bearer token: 'Authorization: Bearer tts-...'. This authenticates your request using the key issued to your account.

How do I handle long texts?

Split your text into parts of up to 4096 characters. Send each part as a separate request to the speech endpoint. Then, join the resulting audio files in your application code. This ensures each chunk is processed within the input limit constraints.

Is streaming supported in the response?

No, streaming is not supported. The API returns the complete audio file after synthesis is finished. There is no WebSocket or real-time partial audio delivery. You receive the full binary response once the request completes, which may take time for long texts.

First request

curl

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

Authentication relies on a single active API key per account, issued via the /get-api-key/ page. Keys follow the format tts-... and must be sent in the Authorization header. This simple scheme avoids complex OAuth flows, allowing immediate integration with existing SaaS notification pipelines.

The key grants access to all endpoints, including speech generation and voice listings. Since only one key is active at a time, rotating credentials is straightforward but requires updating your client configuration promptly to avoid service interruption during the switch.

API Key Format

API Key Format

API keys are issued as strings starting with tts-. They are unique to each account and provide full access to the API. Ensure you copy the key exactly as displayed, as trailing spaces can cause authentication failures.

Keys are generated when you sign up or request a new key. The old key stops working immediately upon issuance of a new one, ensuring no overlap in active credentials.

  • Keys start with tts-
  • One active key per account
  • No scope restrictions

Authorization Header

Authorization Header

Include the key in every request using the standard HTTP Authorization header: Authorization: Bearer tts-.... This is compatible with the OpenAI SDK by setting the base URL to https://api.playtop99.com/v1.

Incorrect or missing headers result in a 401 Unauthorized error. Verify that no extra whitespace or line breaks are included in the header value to prevent silent failures.

Key Rotation

You can issue a new key at any time from your dashboard. The previous key becomes invalid immediately, ensuring secure credential management without downtime if updated correctly.

Rotation is ideal for security audits or if a key is suspected to be compromised. No re-authentication flow is needed beyond updating the stored key in your application.

Endpoints

Sound wave illustration for: Endpoints

The API exposes three primary endpoints for managing speech synthesis and configuration. Use the speech endpoint to convert text into audio, the voices list to preview available presets, and the models list to verify engine versions.

Speech Generation

Send a POST request to /v1/audio/speech with your JSON payload to receive an audio file. The endpoint accepts up to 4096 characters per request and returns the synthesized audio in the specified format, such as MP3 or WAV.

Voices List

Query GET /v1/voices to retrieve the full list of available voice presets, their associated languages, and supported output formats. This allows you to dynamically match voices to your application’s localization needs.

  • Returns 8 presets: aria, nova, luna, sage, felix, milo, atlas, orion
  • Includes metadata on supported languages and formats

Models List

Use GET /v1/models to view the available TTS models. Currently, the API offers tts-1 and tts-1-hd, which share the same engine and pricing structure.

Request Parameters

Sound wave illustration for: Request Parameters

Configuring the speech generation request requires precise handling of three core parameters: model, input text, and voice selection. These fields define the output quality, character limits, and tonal character of the synthesized audio.

Model Selection

Choose between "tts-1" and "tts-1-hd" for standard or high-definition synthesis. Both models use the same engine and pricing tier, so select based on your audio quality requirements without cost implications.

Input Text Length

The API accepts up to 4096 characters per request. For longer content, split the text into chunks, generate audio for each, and join the files. Spaces and punctuation count toward the character limit.

Voice Preset

Select one of eight presets to match your notification style. Female voices include aria, nova, luna, and sage; male options are felix, milo, atlas, and orion. Each voice supports all 23 supported languages.

Response Formats

Sound wave illustration for: Response Formats

The API returns audio files in the format specified by your response_format parameter. Supported options include mp3, wav, opus, flac, and pcm, allowing you to choose the best balance between file size and quality for your specific SaaS infrastructure.

MP3 Output

MP3 is a supported format, offering a compact file size suitable for web delivery and mobile notifications. It is ideal for reducing bandwidth costs while maintaining acceptable audio clarity for most user interfaces.

  • Default format for most integrations
  • Optimized for web and mobile delivery
  • Smallest file size for bandwidth efficiency

WAV Output

WAV provides uncompressed, lossless audio data. This format is suitable for applications requiring immediate playback without decoding overhead or where audio integrity is critical for quality assurance.

  • Uncompressed audio data
  • No decoding overhead for playback
  • Ideal for quality assurance workflows

Lossless Formats

FLAC and PCM offer lossless alternatives. FLAC provides compression without data loss, while PCM delivers raw audio streams. These formats are useful for archival purposes or high-fidelity audio processing pipelines.

  • FLAC: Compressed lossless audio
  • PCM: Raw uncompressed audio stream
  • Suitable for archival or processing pipelines

Speed Control

Sound wave illustration for: Speed Control

Adjust speech playback speed between 0.25x and 4.0x to fit interface constraints or user preferences. This parameter modifies the audio output in real-time without requiring separate voice models, allowing SaaS teams to optimize character consumption for long notifications.

Speed Range 0.25–4.0

Set the speed field in your request body to control voice pacing. Values below 1.0 slow the narration, while values above 1.0 accelerate it.

Real-Time Generation

Long texts generate at roughly real-time speed, processing approximately 25 characters of text per second of audio. Short phrases may take a few seconds to synthesize due to initialization overhead, but complex processing remains minimal.

Queue Impact

Requests are processed sequentially. Under heavy load, your synthesis job may wait in a queue before beginning. This linear processing ensures consistent quality but means concurrent requests from different keys will not accelerate individual generation times.

Speed Control

Error Handling

Sound wave illustration for: Error Handling

Handling errors correctly ensures your application remains resilient during high-volume TTS generation. Understanding HTTP status codes and rate limits allows you to implement robust retry logic without wasting credits on failed requests.

Common HTTP Errors

Returns standard HTTP codes like 400 for bad requests, 401 for invalid keys, and 500 for internal server issues. Failed synthesis requests are free, ensuring you are not charged for errors.

Rate Limit Exceeded

Exceeds the 60 requests per minute limit per key. New accounts start with a 10 requests per minute limit until the first top-up. Implement exponential backoff to handle 429 responses gracefully.

Invalid Input

Returns 400 if input text exceeds 4096 characters or if the voice ID is invalid. Ensure your client splits long texts into chunks before sending requests to avoid input errors.

OpenAI SDK Setup

Sound wave illustration for: OpenAI SDK Setup

The API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing OpenAI SDKs with minimal configuration. By simply updating the base_url to https://api.playtop99.com/v1, your application can authenticate and send requests using standard libraries.

This compatibility ensures that teams already familiar with OpenAI’s integration pattern can adopt our service without learning a new SDK or rewriting core logic. The request shape remains identical, supporting the same JSON body structure for model, input, voice, and format parameters.

Base URL Change

Update your SDK client configuration to point base_url at https://api.playtop99.com/v1. This single change redirects all subsequent API calls to our infrastructure while maintaining the familiar endpoint paths.

SDK Compatibility

The official OpenAI SDKs work out-of-the-box. No custom wrapper is required, as the JSON body structure matches the OpenAI speech endpoint exactly. You can use the same base_url and authentication headers you would use for OpenAI, replacing only the domain.

  • Supports standard OpenAI Python and Node.js SDKs
  • Identical JSON request body structure
  • No additional libraries or dependencies required

Code Example

Here is a minimal Python example using the OpenAI SDK to generate speech. Replace YOUR_API_KEY with your key from /get-api-key/ and set the base_url correctly.

  • ```python
  • import openai
  • client = openai.OpenAI(api_key='tts-...', base_url='https://api.playtop99.com/v1')
  • response = client.audio.speech.create(
  • model='tts-1',
  • voice='nova',
  • input='Hello from Playtop99',
  • response_format='mp3'
  • )
  • response.write_to_file('output.mp3')
  • ```

Rate Limits

Sound wave illustration for: Rate Limits

Rate limits are enforced per API key to ensure fair usage across the network. Understanding these constraints helps SaaS teams design robust retry logic and manage background notification queues effectively.

60 RPM Limit

After your initial top-up, you may send up to 60 requests per minute. This limit applies to the tts-1 and tts-1-hd models collectively. If you exceed this threshold, the API returns a 429 Too Many Requests error. Implement exponential backoff in your integration to handle temporary spikes without dropping notifications.

Pre-Topup Limit

Before your first top-up, the limit is stricter at 10 requests per minute. This allows new accounts to test the service without overwhelming the infrastructure. Once you add USDT (TRC-20), the higher 60 RPM limit activates automatically.

Concurrency

Requests are processed sequentially within the rate limit window. Under heavy load, your request may wait in a queue before synthesis begins. This ensures consistent audio quality but means that bursty traffic patterns might experience slight delays compared to steady-state usage.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Your team receives seamless alerts directly within the unified interface for instant awareness and streamlined collaboration.

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. LibriTTS-R corpus (OpenSLR 141)
  3. openai-python on GitHub
  4. ISO 639 language codes
  5. FFmpeg documentation
  6. LibriVox public-domain audiobooks
  7. OpenAI API reference: create speech
  8. curl documentation
  9. MDN: Web Speech API
  10. IETF RFC 7845: Ogg Opus
  11. Tether (USDT)
  12. Creative Commons Attribution 4.0

More on this site