TransitVoice API Integration for Announcements

By TransitVoice editorial team · Updated 2026-11-19

This guide helps transport product teams integrate SpeakPath’s text-to-speech API for station and vehicle announcements. You will learn how to send text and receive standardized audio files that meet accessibility standards. The API uses a simple JSON format compatible with OpenAI SDKs, allowing you to reuse existing infrastructure for reliable, human-sounding outputs.

We cover authentication, parameter configuration, and rate limits specific to your deployment needs. You will see how to handle long texts by splitting them into manageable chunks and joining the resulting audio files. Examples use real voice presets and transport-relevant settings to ensure your announcements sound clear and professional across all supported languages.

TransitVoice API Integration for Announcements

Frequently asked questions

Which SDK should I use?

You can use the official OpenAI SDKs by changing the base URL to https://api.55gg.info/v1. Alternatively, you can use any standard HTTP client to send POST requests to the /v1/audio/speech endpoint. The request body shape is identical to the OpenAI speech endpoint, making integration straightforward for most developers.

Do I need the OpenAI SDK?

No, you do not need the OpenAI SDK. While the API is compatible with it, you can use any HTTP library or plain HTTP requests. The endpoint accepts standard JSON bodies, so any programming language with HTTP capabilities can interact with the SpeakPath API without specific vendor dependencies.

What is the base URL?

The API base URL is https://api.55gg.info/v1. You should configure your SDK or HTTP client to point to this address. All audio generation requests are sent via POST to https://api.55gg.info/v1/audio/speech, and voice listings are available at GET /v1/voices.

Can I use Python with this API?

Yes, Python works well with this API. You can use the OpenAI Python library by setting the base URL to https://api.55gg.info/v1. Alternatively, use standard libraries like requests or httpx to send JSON payloads to the speech endpoint. Authentication is handled via the Authorization header.

How do I change the voice speed?

Include a speed parameter in your request body, with values between 0.25 and 4.0. The default speed is 1.0. This allows you to adjust announcement pacing for different transport contexts, such as slower speeds for complex station names or faster speeds for brief warnings.

What formats are supported?

The API supports mp3, wav, opus, flac, and pcm formats. Specify the desired format using the response_format field in your request. MP3 is suitable for web players, while WAV and FLAC offer lossless quality for station PA systems. PCM provides raw audio data.

Does the API support SSML?

No, the API does not support SSML. You pass plain text in the input field. If you need specific pronunciation or pauses, you can use standard punctuation or phonetic spelling within the text limit. The system guesses language from the script if not explicitly set.

Is streaming supported?

No, streaming is not supported. The API returns the complete audio file in the response after synthesis is finished. You receive a single audio file, not partial chunks. This ensures reliable delivery for transport announcements where file integrity is critical for playback systems.

What happens if I exceed rate limits?

You are limited to 60 requests per minute per key (10 before the first top-up). If you exceed this, requests may queue or fail. Failed requests are free, so you are not charged for attempts that do not complete successfully due to rate limiting or other errors.

Can I generate audio asynchronously?

The API processes requests sequentially, so long texts may take time. There is no async webhook or job ID system. You must wait for the response containing the audio file. For very long announcements, split the text into parts and join the resulting audio files.

How do I handle 4096 character limits?

Each request accepts up to 4096 characters. For longer announcements, split your text into chunks of this size. Generate audio for each chunk separately, then concatenate the resulting audio files to create the final announcement. This ensures high quality and avoids truncation.

Is the response format always audio?

Yes, the response body contains the audio file in the requested format. If an error occurs, you receive an error JSON object instead. Successful requests return the binary audio data directly, which you can save or play immediately.

Can I use a custom domain?

The API is hosted on api.55gg.info. You cannot change the base domain for the API endpoint itself. However, you can use your own domain for the final audio playback or storage after receiving the file. The API key remains tied to your account on this site.

Do I need to install a specific library?

No specific library is required. You can use any HTTP client. If you prefer convenience, the OpenAI SDK works by adjusting the base URL. Otherwise, standard libraries like requests (Python), axios (JavaScript), or curl are sufficient. The API uses standard JSON and HTTP methods.

First request

curl

curl https://api.55gg.info/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.55gg.info/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.55gg.info/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

Authenticate your transit announcement API calls by including a Bearer token in the Authorization header. This single key validates your account and tracks usage against your balance. Keep this credential secure in your backend configuration rather than exposing it in client-side code.

SpeakPath issues one active key per account to simplify integration. You can generate a new key at any time through your dashboard, ensuring you maintain control over your access credentials without complex management overhead.

Use Bearer token in Authorization header

Use Bearer token in Authorization header

Include the header Authorization: Bearer tts-... in every request to https://api.55gg.info/v1. This standard format ensures compatibility with existing HTTP clients and SDKs used by your transport software.

The token authenticates your identity and links generated audio credits to your specific station or vehicle fleet account.

  • Header name: Authorization
  • Format: Bearer tts-<your_key>
  • Required for all POST /v1/audio/speech requests

One active key per account

One active key per account

Each account holds exactly one active API key. This reduces configuration errors and simplifies debugging when multiple vehicles or stations use the same integration.

You can view and copy your current key directly from the /get-api-key/ dashboard page.

Revoke old keys instantly on new issuance

When you generate a new key, the previous one stops working immediately. This allows you to rotate credentials without a waiting period or grace window, ensuring that any compromised key is instantly invalid.

Old keys cannot be manually deactivated; issuing a new one is the only way to revoke access.

  • New key generation revokes old key instantly
  • No waiting period for deactivation
  • Recommended for security rotations

Endpoint basics

Sound wave illustration for: Endpoint basics

The core synthesis endpoint is POST https://api.55gg.info/v1/audio/speech. Send your announcement text in a JSON payload to receive a standardized audio file. This workflow delivers static audio assets suitable for transport station displays or vehicle PA systems without complex infrastructure.

The request body mirrors the OpenAI speech endpoint structure. You define the text input, select a voice preset, and specify the desired output format. This compatibility allows you to use existing OpenAI SDKs by simply updating the base URL to our API domain.

POST to /v1/audio/speech

Direct your requests to this specific endpoint. The service processes your text and returns the synthesized audio file directly in the response body, ready for immediate playback or storage in your transport management system.

  • Endpoint: https://api.55gg.info/v1/audio/speech
  • Method: POST
  • Returns: Audio file (mp3, wav, opus, flac, or pcm)

JSON body format

Structure your request as a JSON object. Include the model, input (your text up to 4096 characters), voice, and response_format. Optional fields like speed and language allow fine-tuning of the announcement's delivery and clarity.

  • Content-Type: application/json
  • Required: model, input, voice, response_format
  • Optional: speed, language

Same shape as OpenAI speech endpoint

If you already use the OpenAI SDK for other services, you can integrate SpeakPath with minimal code changes. Just update the base_url to https://api.55gg.info/v1 and use your SpeakPath API key for authentication.

  • Compatible with official OpenAI SDKs
  • Simple base URL change
  • Familiar request structure

Required parameters

Sound wave illustration for: Required parameters

The API requires three core fields to generate audio: model, input, and voice. These define the synthesis engine, the content to speak, and the speaker's identity. All three must be present in the JSON body for a successful request.

Model: tts-1 or tts-1-hd

Select tts-1 for standard quality or tts-1-hd for higher fidelity. Both use the same underlying engine and pricing ($0.01 per 1,000 characters), so choose based on your audio clarity needs.

Input: text up to 4096 characters

The input field accepts your announcement text. It supports up to 4,096 characters per request. For longer messages, split the text into smaller chunks and join the resulting audio files manually.

  • Spaces and punctuation count toward the character limit.

Voice: select from 8 presets

Choose one of eight licensed voices. Female options include Aria (warm narrator), Nova (upbeat), Luna (storytelling), and Sage (calm). Male options include Felix (energetic), Milo (friendly), Atlas (neutral news), and Orion (deep documentary).

  • Any voice can speak any of the 23 supported languages.

Optional parameters

Sound wave illustration for: Optional parameters

Beyond the core parameters, you can tailor the audio output to fit specific playback environments. Adjusting the response format, speed, and language ensures the generated announcements integrate smoothly into your existing transport infrastructure.

Response format: mp3, wav, opus, flac, pcm

Select the audio container that matches your playback hardware. MP3 offers small file sizes for efficient storage, while WAV and FLAC provide lossless quality for high-fidelity station speakers. Use PCM for raw data processing or OPUS for bandwidth-constrained mobile apps. Note that OPUS is a compression format, not a streaming protocol.

  • mp3: Standard, compact
  • wav: Lossless, high quality
  • opus: Efficient compression
  • flac: Lossless compression
  • pcm: Raw audio data

Speed: 0.25 to 4.0 multiplier

The speed parameter allows you to adjust the playback rate from 0.25x to 4.0x. This is useful for creating urgent alerts that need to be concise or for slowing down announcements in noisy environments to improve clarity for passengers.

  • Range: 0.25–4.0
  • Use for urgency or clarity

Language: ISO code for disambiguation

While the API guesses language from the script, setting the language parameter explicitly ensures correct pronunciation for mixed-language texts or ambiguous scripts. For example, Latin-script text defaults to English, so specify es or fr if needed.

  • Ensures accurate pronunciation
  • Handles mixed-language announcements

Rate limits

Sound wave illustration for: Rate limits

The API enforces a limit of 60 requests per minute for each active key. This allows product teams to generate announcements efficiently during peak deployment windows without overwhelming the service.

60 requests per minute per key

Once your account is funded, you can send up to 60 synthesis requests every minute. This capacity supports batch processing for multiple station announcements or vehicle updates simultaneously.

10 requests per minute before first top-up

New accounts start with a lower threshold of 10 requests per minute. This limits initial usage while you validate the integration with your transit systems before purchasing additional credit.

Requests queue under load

Requests are processed sequentially. If you exceed the limit or experience high demand, new requests may wait in a queue. Longer texts take more time to synthesize, so plan your generation cycles accordingly.

Rate limits

Handling long texts

Sound wave illustration for: Handling long texts

When an announcement exceeds 4096 characters, you must split the text into smaller chunks before sending requests. This ensures each segment fits the API's input limit without truncation.

Generate audio for each chunk individually, then join the resulting files. This approach works whether you process chunks sequentially or in parallel, keeping your infrastructure simple and reliable.

Split text into 4096-char chunks

Divide your announcement text into segments of up to 4096 characters. Count spaces and punctuation as characters. This ensures every request fits the API's limit.

  • Count all characters, including spaces and punctuation.
  • Keep segments under 4096 characters to avoid truncation.

Generate audio for each chunk

Send each chunk as a separate POST request to the speech endpoint. Each request returns a distinct audio file. Processing is sequential, so under load, requests may queue.

  • Use the same voice and speed for all chunks.
  • Ensure consistent audio quality across segments.

Join audio files client-side or server-side

Combine the returned audio files in the order of the original text. You can do this on the client or server side. The result is a single, continuous announcement file.

  • Maintain the original order of chunks.
  • Use standard audio libraries for joining files.

Error handling

Sound wave illustration for: Error handling

Transit systems require reliable audio delivery, and API errors can interrupt announcement schedules. The SpeakPath API returns standard HTTP status codes to indicate success or failure. Understanding these codes helps your integration distinguish between configuration issues and temporary service disruptions.

Check HTTP status codes

Use 200 OK for successful synthesis. A 400 Bad Request indicates invalid parameters, such as exceeding the 4096-character limit or using an invalid model or voice. A 401 Unauthorized means your Bearer token is invalid. A 429 Too Many Requests signals you have hit the rate limit of 60 requests per minute.

Review error message body

Every error response includes a JSON body with a descriptive message. Read this message to identify the exact cause, such as an invalid model name or an unsupported response format. This detail helps you fix configuration issues quickly without guessing.

Retry on transient errors

Implement exponential backoff for 503 Service Unavailable or 504 Gateway Timeout errors. These indicate temporary queueing or server load. Do not retry 4xx errors unless you are correcting the request parameters.

Example: Curl request

Sound wave illustration for: Example: Curl request

Generate audio announcements for transit vehicles with a single command. This approach delivers standardized MP3 files ready for playback systems, ensuring consistent quality across all stations.

Adjust playback speed to match your timing needs. Specify your preferred voice and model to align with your brand’s accessibility standards without extra infrastructure.

Basic MP3 generation

Send a POST request to the speech endpoint with your text. The API returns an audio file directly in the response body.

  • Use tts-1 or tts-1-hd for the model
  • Set response_format to mp3
  • Include your text in the input field

Include speed parameter

Control the playback rate between 0.25 and 4.0. This ensures announcements fit within scheduled dwell times at stations or buses.

  • Set speed to 1.0 for normal pace
  • Use higher values for quick alerts
  • Lower values aid comprehension for diverse audiences

Specify voice and model

Select from eight presets like nova or atlas. Each voice offers distinct tones suitable for different transit contexts.

  • Use voice parameter to select a preset
  • Combine with language for non-English text
  • Ensure input is under 4096 characters

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Pay attention to passenger comments regarding audio clarity and volume.

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. Creative Commons Attribution 4.0
  3. LibriTTS-R corpus (OpenSLR 141)
  4. MDN: Web Speech API
  5. FFmpeg documentation
  6. TRON developer hub: TRC-20
  7. Node.js documentation
  8. Tether (USDT)
  9. openai-python on GitHub
  10. ISO 639 language codes
  11. OpenAI API reference: create speech
  12. openai-node on GitHub

More on this site