Frequently asked questions
What is the API endpoint URL?
Send your requests to POST https://api.playc54.com/v1/audio/speech. This endpoint accepts JSON bodies containing your text, selected voice, and desired audio format. It follows the same request shape as the OpenAI speech endpoint, making integration straightforward for teams already familiar with standard TTS workflows.
How do I authenticate my requests?
Include your API key in the Authorization header using the Bearer scheme: Authorization: Bearer tts-.... Each account holds one active key. You can issue a new key at any time via the dashboard, which immediately invalidates the previous key for security.
Can I use the OpenAI Python SDK?
Yes. The API matches the OpenAI speech endpoint shape. You can use the official OpenAI SDKs by changing the base_url to https://api.playc54.com/v1 and providing your site-specific API key. This allows you to leverage existing code patterns without rewriting your integration logic.
What is the maximum text length?
Each request supports up to 4096 characters of input text. For longer announcements, split your text into parts of this limit and join the resulting audio files. This ensures consistent processing speed and avoids timeouts, keeping your transit app responsive during peak usage hours.
Are there rate limits on the API?
New keys are limited to 10 requests per minute. Once you top up, the limit increases to 60 requests per minute. Requests are processed one after another, so under load a request may wait in a queue. Monitor your usage dashboard to ensure your station announcements play without delay.
How do I handle API errors?
Failed synthesis requests are free; any charge is returned in full if the process fails. Check your response status codes and retry logic. Since requests are processed one after another and may wait in a queue under load, implement exponential backoff to handle temporary delays.
Can I stream the audio response?
No. The API returns the complete audio file in the response body. There is no WebSocket or real-time partial audio streaming available. You must wait for the full file to generate before playing it.
Does the API support SSML?
No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You control pacing and tone by adjusting the speed parameter between 0.25 and 4.0. For precise control, split your text into separate requests for each voice or speed change.
How do I specify a language?
Pass the optional language field with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always set the language explicitly to ensure accurate pronunciation across our 23 supported languages.
Is the audio format configurable?
Yes. You can choose from mp3, wav, opus, flac, or pcm using the response_format field. MP3 is efficient for app notifications, while WAV or FLAC offers higher quality for digital signage. All generated files include an inaudible watermark identifying them as synthetic speech.
Can I change the voice mid-request?
No. Each request generates audio for a single voice preset. To change voices, split your text into multiple requests, each specifying a different voice parameter. Join the resulting audio files on your end. This gives you full control over narrator styles in your transit app.
How are characters counted?
Spaces and punctuation count as characters. The price is $0.01 per 1,000 characters. Ensure your text length stays within the 4096-character limit per request. Accurate character counting helps you predict costs and manage your balance effectively, especially for long-form announcements or detailed instructions.
Is there a SDK for mobile apps?
No. There is no official mobile SDK, browser extension, or WordPress plugin. Use the standard HTTP requests or the OpenAI SDK by adjusting the base URL. This lightweight approach works well with any mobile framework, allowing you to integrate TTS directly into your existing app architecture.
How do I revoke my API key?
You can issue a new API key at any time from your dashboard. The old key stops working immediately when the new one is active. This provides instant revocation without needing to contact support.
First request
curl
curl https://api.playc54.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.playc54.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.playc54.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 |
Quick Start with API Key
To start generating transit announcements, navigate to the /get-api-key/ page and sign in using Google or create an account with your email and password. Your dashboard will immediately display your unique API key, current balance, and a ready-to-use curl example for testing.
Once you have your key, you can begin sending text to the API. The key is the sole credential required for authentication, so ensure it is stored securely within your transport product’s configuration environment to avoid unauthorized usage charges.
Get your key
Visit the /get-api-key/ page to create your account. Signing in with Google grants you a free trial credit of $0.50, valid for 7 days, which covers approximately 50,000 characters. Accounts created with email and password do not include this initial trial credit.
Keep it secure
Your API key acts as the password for your account. Treat it like a secret; do not expose it in client-side code or public repositories. Store it in your server environment variables where only your backend services can access it.
Regenerate if needed
If you suspect your key has been compromised, you can issue a new one at any time from your dashboard. The old key stops working instantly, ensuring no further requests can be made with the compromised credential.
First Request with Curl
To generate station announcements or app notifications, send a POST request to https://api.playc54.com/v1/audio/speech. This endpoint accepts your text and returns synthesized audio; generation takes a few seconds for short phrases and roughly real time for long texts, so requests may wait in a queue under load.
The API follows a standard JSON structure. You specify the model, input text, voice preset, and desired audio format. This simplicity allows product teams to integrate speech generation without managing complex infrastructure.
POST endpoint
Send your request to POST https://api.playc54.com/v1/audio/speech. This is the single entry point for all synthesis tasks. Ensure your Authorization header includes your Bearer token for authentication.
JSON body format
Include model (e.g., "tts-1"), input (text up to 4096 characters), voice (one of eight presets like 'aria' or 'atlas'), and response_format (mp3, wav, opus, flac, or pcm). You may optionally specify a language ISO code.
Example body: `{"model": "tts-1", "input": "Next stop: Central Station", "voice": "atlas", "response_format": "mp3"}`. Spaces and punctuation count toward the character limit.
Audio response
The API returns the audio file directly in the response body with the specified format. For MP3, the file is ready for immediate playback in your transit app or digital signage player.
If the synthesis fails, you receive an error code (e.g., 400) and no charge is applied. Successful requests return the binary audio data directly in the response body.
OpenAI SDK Compatibility
ClearCast uses the same request shape as OpenAI’s speech endpoint, so you can swap in our API with minimal code changes. Simply update your SDK’s base URL to point to our servers and use your ClearCast API key.
This compatibility means you can leverage existing tools and libraries without rewriting your entire audio generation pipeline. It works seamlessly with standard HTTP clients and popular SDKs.
Change base URL
Update your SDK configuration to use our API base URL: https://api.playc54.com/v1. This directs your requests to ClearCast’s servers while keeping the standard endpoint structure intact.
Use official SDKs
The official OpenAI SDKs work directly with ClearCast. Just ensure you are using the correct base URL and your ClearCast API key for authentication.
Drop-in replacement
Since the request shape matches, you can replace OpenAI’s endpoint with ours in most cases. This makes integration quick and straightforward for transit apps already using TTS services.
Supported Formats
The API returns audio in four standard formats, letting you choose the right balance of file size and quality for your transit displays or mobile apps.
MP3 for web
MP3 is the default and most efficient choice for web players and digital signage. It offers small file sizes with good clarity, making it ideal for quick station announcements or in-app notifications where bandwidth matters.
WAV for quality
Choose WAV when you need uncompressed, high-fidelity audio for local playback or professional grading. This format preserves every detail of the synthetic voice, ensuring crisp sound for high-end digital signage systems without compression artifacts.
FLAC and OPUS
FLAC provides lossless compression for archival storage, keeping file sizes smaller than WAV while retaining full quality. OPUS is a supported format for efficient file sizes and quality.
Rate Limits and Quotas
Rate limits protect our shared infrastructure during peak transit hours. Each API key allows 60 requests per minute, which is sufficient for most station announcement batches. If you exceed this, you will receive a 429 error until the window resets, or your request may wait in a queue if the server is under load.
Before your first top-up, the limit is stricter to prevent abuse. We allow only 10 requests per minute during the free trial period. Once you add credit via USDT, the limit automatically increases to the full 60 requests per minute.
60 requests per minute
This is the standard limit for all active accounts. It applies to both tts-1 and tts-1-hd models. You can monitor your usage in the dashboard to avoid interruptions during high-volume broadcasts.
- Applies per API key
- Resets every 60 seconds
- Covers all response formats
10 requests before top-up
Free trial accounts start with a lower limit. This ensures fair usage while you test the API. The limit lifts instantly after your first successful USDT transfer.
Queue handling
Requests are processed one after another, so under load a request may wait in a queue. Long texts may take a few seconds to generate, so plan your API calls accordingly.

Handling Errors
Errors in the ClearCast API return standard HTTP codes to help you debug integration issues quickly. Understanding these responses ensures your transit announcement pipeline stays reliable without unnecessary retries or wasted credits.
Most failures are related to authentication, rate limits, or malformed input. Below are the specific codes you will encounter and how to handle them in your transport app workflow.
429 Too Many Requests
You receive this status when exceeding the 60 requests per minute limit. If you are below the first top-up, the limit is stricter at 10 requests per minute.
Requests are processed one after another, so under load a request may wait in a queue. Implement exponential backoff in your app to handle transient spikes gracefully.
- Check the
Retry-Afterheader for guidance on when to retry. - Monitor your usage dashboard to anticipate high-volume announcement bursts.
401 Unauthorized
This error indicates your API key is missing, invalid, or has been revoked.
Ensure you include the Authorization: Bearer tts-... header in every request. If you regenerated your key, the old one stops immediately.
- Verify your key starts with
tts-. - Check that no trailing spaces exist in the token.
400 Bad Request
This response means the JSON body is malformed or contains invalid values.
Common causes include text exceeding 4096 characters, an unsupported voice name, or a speed value outside the 0.25–4.0 range. Check the error message in the response body for specific field details.
- Ensure
inputis under 4096 characters. - Validate
response_formatagainst mp3, wav, opus, flac, or pcm.
Voices and Languages
ClearCast provides eight distinct voice presets tailored for clear transit announcements and app notifications. Each voice is engineered for specific tonal needs, from warm narrators to energetic promo styles, ensuring your audio fits the context perfectly.
8 preset voices
Choose from female voices like Aria (warm, clear narrator), Nova (bright, upbeat), Luna (soft, storytelling), and Sage (calm, instructional). Male options include Felix (energetic, promo), Milo (friendly, conversational), Atlas (neutral, news), and Orion (deep, documentary). All voices are based on licensed recordings from LibriTTS-R and LibriVox public-domain audiobook readings.
- Aria: warm, clear narrator
- Nova: bright, upbeat
- Luna: soft, storytelling
- Sage: calm, instructional
- Felix: energetic, promo
- Milo: friendly, conversational
23 languages supported
Our API supports 23 languages, including English, Spanish, German, French, Japanese, Korean, and Hindi. Any voice can speak any of these supported languages, allowing you to localize station announcements or app notifications without managing multiple voice profiles.
- Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Auto-detection
The API automatically detects the language from the input text script. For Latin script text, it defaults to English. For other languages, you should explicitly set the language parameter to ensure accurate pronunciation and avoid defaulting to English for non-English Latin-script text.
Authentication Details
Your API key authenticates every request to the ClearCast engine. Include it in the HTTP header as a Bearer token, ensuring no extra spaces or characters break the string. This single key grants access to your account’s balance and usage history.
Bearer token format
Send the header Authorization: Bearer tts-... with every POST request. The token must match exactly what you see in your dashboard. If the format is incorrect, the API returns a 401 Unauthorized error, preventing any audio generation.
Single active key
Each account holds only one active key at a time. You can regenerate it via the dashboard at any time. The previous key stops working immediately, so update your transit apps or notification services promptly after rotation.
Instant revocation
Revocation happens in real-time. If you suspect a leak or need a fresh start, generate a new key from your account page. The old key is invalid instantly, ensuring your station announcements and digital signage remain secure without delay.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Aria delivers a soft, storytelling quality that works well for detailed route explanations or station history segments.
23 languages
Any voice speaks any of these languages.
