Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or email and password. Your account is specific to this site. Once registered, you receive one active API key starting with 'tts-'. You can issue a new key at any time, which immediately invalidates the previous one.
What is the base URL?
The API base URL is https://api.cx255.info/v1. Use this for all requests, including POST /v1/audio/speech, GET /v1/voices, and GET /v1/models. This endpoint handles authentication via the Bearer token in your Authorization header.
Does the API support SSML?
No, the API does not support SSML. You send plain text in the input field. If you need pauses or emphasis, you must manage that logic in your application code before sending the request to the endpoint.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work perfectly. Change the base_url to https://api.cx255.info/v1 and provide your RoadVoce API key. The request shape matches the OpenAI speech endpoint exactly, allowing for easy integration into existing projects.
What are the rate limits?
The limit is 60 requests per minute per key. If your account has not yet topped up, the limit is 10 requests per minute. These limits apply to each active API key independently.
How do I split long texts?
Split your text into parts of up to 4096 characters each. Send each part as a separate request and join the resulting audio files in your application. This ensures compatibility with the single-request character limit.
What happens if I exceed the limit?
Requests are processed sequentially. If you exceed the rate limit, your request may wait in a queue until capacity is available. Failed requests are free, but successful ones are charged. Ensure your client handles retries gracefully.
Is streaming supported?
No, streaming is not supported. You receive the complete audio file in the response after synthesis finishes. There is no WebSocket or real-time partial audio delivery. You must wait for the full file to be generated.
How do I handle errors?
Check the HTTP status code in the response. If synthesis fails, the charge is returned in full. Inspect the error message in the JSON body to identify issues like invalid voices, unsupported languages, or network problems.
Are requests queued?
Yes, requests are processed one after another. Under load, a request may wait in a queue before synthesis begins. This ensures orderly processing but may increase latency during high-traffic periods compared to immediate execution.
What is the max text length?
The maximum input text length is 4096 characters per request. Spaces and punctuation count toward this limit. For longer texts, split the content into chunks of 4096 characters or fewer and process them individually.
Do I need to install a SDK?
No, you do not need to install a specific SDK. You can use the official OpenAI SDK by changing the base URL, or use plain HTTP requests. Any HTTP client capable of sending JSON works fine.
Is the API compatible with Python?
Yes, the API is fully compatible with Python. Use the official OpenAI Python SDK by configuring the base_url to https://api.cx255.info/v1. Alternatively, use the requests library or any standard HTTP client to send POST requests.
Can I use cURL?
Yes, cURL works perfectly. Use the provided curl example on the /get-api-key/ page as a template. Send a POST request to https://api.cx255.info/v1/audio/speech with your API key in the Authorization header and JSON body.
First request
curl
curl https://api.cx255.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.cx255.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.cx255.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
Secure your TTS integration by passing a Bearer token in the Authorization header. This key authenticates your requests to the API, ensuring that only authorized applications can consume your character quota.
Maintain control over your account security with a simple key management system. You can issue a new key at any time, which immediately invalidates the previous one, allowing for rapid response to potential exposure.
Bearer token usage
Include your unique API key in every request header as Authorization: Bearer <your_key>. This standard method ensures your navigation or automotive app is recognized by the engine without complex setup.
One active key per account
Each account holds only one active key at a time. This simplifies tracking usage and billing, as all requests are attributed to a single identifier, making it easier to monitor consumption across your startup's projects.
Key rotation policy
Generate a new key via your dashboard whenever needed. The old key stops working immediately upon the new key's creation, ensuring no overlap or ambiguity in which token is currently valid for your API calls.
Endpoint Overview
RoadVoce provides three core endpoints for navigation app developers. The primary endpoint handles speech synthesis, while the secondary endpoints allow you to dynamically fetch available voice presets and model configurations without hardcoding them.
POST /v1/audio/speech
Send text and receive an audio file. This endpoint accepts JSON bodies with fields like model, input, voice, response_format, and speed. It mirrors the OpenAI speech endpoint structure, allowing you to switch SDKs easily.
- Accepts up to 4096 characters of text.
- Returns audio in formats like MP3, WAV, or FLAC.
GET /v1/voices
Retrieve the full list of available voices, their associated languages, supported formats, and pricing details. This helps you dynamically update your app's voice selection menu without manual updates.
- Returns 8 voice presets with metadata.
GET /v1/models
Fetch the current model configurations. Use this to verify which models are active and their specific capabilities before making synthesis requests.
- Lists available model IDs and versions.
Request Parameters
Configure the synthesis engine and voice selection to match your navigation or automotive app's tone. Each parameter directly influences the audio output's style, language clarity, and compatibility with your existing codebase.
Model: tts-1 or tts-1-hd
Select "tts-1" for standard quality or "tts-1-hd" for higher fidelity. Both models use the same engine and price, so you can switch without changing your integration logic.
Voice: 8 presets
Choose from eight licensed voices based on public-domain audiobook recordings. Options include female presets like Aria and Nova, and male presets like Felix and Atlas, ensuring natural-sounding instructions across diverse scenarios.
- Aria: Warm, clear narrator
- Felix: Energetic, promo
- Atlas: Neutral, news
- Orion: Deep, documentary
Language: optional ISO code
Provide an optional ISO language code to ensure accurate pronunciation. If omitted, the system guesses the language from the script, defaulting to English for Latin text, which helps avoid mispronunciations in non-English locales.
Response Formats
Specify the desired output format via the response_format parameter. The API returns the synthesized audio file directly in the HTTP response body, allowing you to save or stream it to your vehicle's audio system immediately.
MP3, WAV, Opus, FLAC, PCM
Choose from MP3, WAV, Opus, FLAC, or PCM based on your app's needs. MP3 offers a balance of quality and file size for navigation prompts, while PCM provides raw, uncompressed audio for playback in automotive environments.
Audio file in response
The entire audio file is returned in a single response. For long texts, you must split the input into chunks of up to 4096 characters and join the resulting audio files client-side to maintain continuity.
No streaming support
This API does not support WebSocket or streaming partial audio. You receive the complete file only after synthesis finishes, so plan your UI to show a loading state while the audio is being generated.
Rate Limits
Understanding rate limits helps you plan your TTS integration for navigation and automotive apps. Our API enforces strict limits to ensure stable performance for all users. You need to know your quota to avoid interruptions during voice synthesis.
Rate limits apply per API key, so each account has its own independent quota. This setup allows you to manage multiple projects or environments without cross-account interference. Plan your requests accordingly.
60 requests per minute
Once you have topped up your account, you can make up to 60 requests per minute. It allows you to generate audio files at a steady pace without exceeding the quota.
- Limit: 60 requests/minute per key
- Applies to all endpoints
- Stable performance under normal load
10 per minute initially
New accounts start with a lower limit of 10 requests per minute. This allows you to test the API without exceeding your quota. You can increase this limit by topping up your account with USDT.
- Initial limit: 10 requests/minute
- Increase by topping up
- Test before scaling
Queue under load
If you exceed your rate limit, requests are processed one after another. This may cause delays in audio generation. Requests are queued until your quota resets, ensuring no data is lost.
- Requests queued if limit exceeded
- Processed sequentially
- No data loss

Text Input Limits
To keep latency low for navigation cues, each API call accepts a maximum of 4,096 characters. This limit applies to the total input, including spaces and punctuation. For short directions, a single request is usually sufficient.
4096 characters max
Since texts are processed sequentially, keeping requests concise helps avoid queue delays during high load. Long route descriptions or detailed turn-by-turn instructions should be divided into logical segments, each under this 4,096-character threshold.
Split long texts
Split your input into multiple requests, each containing a portion of the text. Ensure each segment is coherent and under the character limit to maintain consistent audio quality and predictable processing times.
Join audio files
Receive separate audio files for each split segment. Your application must concatenate these files into a single continuous audio stream for playback. This approach ensures that even lengthy navigation instructions play smoothly without exceeding API limits.
Error Handling
When the synthesis engine cannot process your request, you are not charged. This ensures that transient issues like temporary overload or invalid input do not drain your balance, keeping your API usage costs predictable for your navigation app’s audio generation pipeline.
Failed requests are free
If the TTS service returns an error status, the request is marked as failed and no characters are deducted from your account. This applies to both invalid parameters and internal processing failures, ensuring you only pay for successfully generated audio files.
Standard HTTP errors
The API returns standard HTTP status codes to indicate the result. Use 4xx codes for client-side issues like missing keys or invalid voices, and 5xx for temporary service disruptions. Check the response body for a detailed error message to debug your integration quickly.
- 400: Bad Request (invalid parameters)
- 401: Unauthorized (invalid or missing API key)
- 429: Too Many Requests (rate limit exceeded)
- 500: Internal Server Error (temporary service issue)
Charge returned on failure
If synthesis fails, the charge is returned in full. You do not need to submit a support ticket for this; the system handles refunds for failed syntheses instantly.
OpenAI SDK Integration
Integrate RoadVoce’s TTS API seamlessly using the official OpenAI SDKs. Simply update the base_url to https://api.cx255.info/v1 and supply your API key. This allows you to leverage familiar libraries without rewriting your client code.
The API follows the same request shape as OpenAI’s speech endpoint, ensuring direct compatibility. You can generate audio files for navigation prompts or automotive instructions using standard parameters like model, voice, and input.
Change base_url
Update your SDK configuration to point to https://api.cx255.info/v1. This redirects all requests to our infrastructure while maintaining the familiar OpenAI interface structure.
Ensure your authentication header remains Bearer tts-... as usual.
- Base URL: https://api.cx255.info/v1
Use official SDKs
Leverage the official OpenAI SDKs (Python, Node.js, etc.) directly. No custom client library is required, reducing integration time for your development team.
The SDK handles request serialization and response parsing exactly as expected for TTS endpoints.
Compatible request shape
Pass model (tts-1 or tts-1-hd), voice (e.g., 'nova'), input (text up to 4096 characters), and response_format.
The API returns an audio file directly in the response body, matching the standard OpenAI speech output format.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This approach maintains audio continuity while respecting character limits per request.
23 languages
Any voice speaks any of these languages.
