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.mp3Python (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 | |
|---|---|
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 |
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
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
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
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
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
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
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.

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
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
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-1ortts-1-hdfor the model - Set
response_formattomp3 - Include your text in the
inputfield
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
speedto1.0for 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
voiceparameter to select a preset - Combine with
languagefor non-English text - Ensure
inputis 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.
23 languages
Any voice speaks any of these languages.
