ClearCast API: Text-to-Speech for Transit Apps

By ClearCast editorial team · Updated 2026-11-18

This guide helps transport product teams integrate natural-sounding station announcements and app notifications. You will learn how to send text and receive audio files using standard HTTP requests. The documentation covers setup, SDK compatibility, and error handling for digital signage and transit systems.

Get your API key and start generating crisp audio immediately. We explain how to manage voices, handle rate limits, and structure your requests. Whether you are building a mobile app or a public display system, this page provides the concrete steps to get your TTS engine running.

ClearCast API: Text-to-Speech for Transit Apps

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

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

Quick Start with API Key

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

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

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

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

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

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

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

Rate Limits and Quotas

Handling Errors

Sound wave illustration for: 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-After header 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 input is under 4096 characters.
  • Validate response_format against mp3, wav, opus, flac, or pcm.

Voices and Languages

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

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

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. FFmpeg documentation
  3. curl documentation
  4. IETF RFC 7845: Ogg Opus
  5. openai-python on GitHub
  6. MDN: Web Speech API
  7. TRON developer hub: TRC-20
  8. ISO 639 language codes
  9. W3C WAI: making audio and video accessible
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. Tether (USDT)
  12. OpenAI API reference: create speech

More on this site