Frequently asked questions
What is the API endpoint for speech generation?
Send a POST request to https://api.cph2699.info/v1/audio/speech. Include your JSON body with the text, voice selection, and desired audio format. This endpoint handles the synthesis process and returns the generated audio file directly in the response.
How do I authenticate with the API?
Include your API key in the request header as Authorization: Bearer tts-.... You receive one active key per account. If you issue a new key, the previous one stops working immediately, ensuring secure access to your navigation voice services.
Can I use the official OpenAI SDK?
Yes. The API uses the same request shape as the OpenAI speech endpoint. You can use the official OpenAI SDKs by simply changing the base_url to https://api.cph2699.info/v1 and providing your NavVoce API key for authentication.
What are the supported audio formats?
You can choose from mp3, wav, opus, flac, or pcm. Select the format that best fits your in-car infotainment system’s playback requirements. Each format is optimized for different bandwidth and quality needs within your automotive voice interface.
What is the character limit per request?
Each request supports up to 4096 characters of input text. This limit applies to the total text sent in a single API call, including spaces and punctuation. For longer navigation instructions, you will need to split the text into multiple requests.
How fast is the API under load?
Requests are processed sequentially, so under load, a request may wait in a queue. Typical speed is roughly real-time for long texts, generating about 25 characters per second. Short phrases may take a few seconds to synthesize.
What happens if I exceed the rate limit?
The rate limit is 60 requests per minute per key. If you exceed this, you will receive a 429 Too Many Requests error. Before your first top-up, the limit is lower at 10 requests per minute.
How do I handle long navigation texts?
Split the text into parts of up to 4096 characters. Send each part as a separate request and then join the resulting audio files. This ensures smooth playback of complex navigation instructions without hitting the single-request character limit.
Is SSML supported in the API?
No, SSML is not supported. The API accepts plain text input only. You cannot use SSML tags to control pacing or emphasis. For precise control, you must manage timing and pauses by splitting your text into separate requests.
Can I specify the language explicitly?
Yes, you can set the language field to an ISO code. This is recommended for non-English Latin-script text to ensure correct pronunciation. If omitted, the language is guessed, defaulting to English for Latin scripts, which may cause errors in other languages.
What is the default language for Latin text?
If the language field is not set, the system guesses the language. For text using Latin script, it defaults to English. To ensure accurate synthesis for other languages like German or Spanish, you should explicitly set the language code.
Are there any voice cloning options?
No, custom voice cloning is not offered. You choose from eight preset voices like Aria, Nova, or Atlas. These are based on licensed recordings and cannot be customized or cloned from your own audio samples for specific brand voices.
How do I rotate my API key?
You can issue a new API key at any time from your account dashboard. When you generate a new key, the old one stops working immediately. This ensures that only your current active key can access the API services.
What is the minimum speed setting?
The minimum speed setting is 0.25. You can adjust the speed between 0.25 and 4.0 to fit your navigation style. Slower speeds may be useful for complex directions, while faster speeds help keep up with driving pace.
First request
curl
curl https://api.cph2699.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.cph2699.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.cph2699.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 and Keys
To start generating voice for your in-car interface, you need an API key. Create an account on our /get-api-key/ page using Google or email. The dashboard displays your active key, current balance, and usage statistics immediately.
Get your API key
Sign up to receive your key. Accounts created via Google include a free trial credit of $0.50, valid for 7 days. Email-only accounts start with zero balance and require a USDT top-up to begin.
Bearer token format
Include your key in the HTTP header as Authorization: Bearer tts-.... This format is compatible with standard OpenAI SDKs when you adjust the base URL to our API endpoint.
Key rotation and limits
You have one active key per account. Issuing a new key immediately invalidates the old one. Each key supports 60 requests per minute, or 10 requests before your first top-up.
- One active key per account
- New key invalidates old instantly
- 60 requests/minute limit
- 10 requests before top-up
Quickstart with cURL
Get your API key from the dashboard and run this cURL command to generate your first audio file. This example synthesizes a simple navigation instruction using the Nova voice.
The API returns the audio file in the response body. Save the output to a local file and play it to verify the synthesis quality before integrating it into your infotainment system.
First request example
Run this command in your terminal, replacing YOUR_API_KEY with your actual key.
```bash curl -X POST https://api.cph2699.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Turn left in 200 meters.", "voice": "nova", "response_format": "mp3"}' \ -o navigation_instruction.mp3 ```
JSON body structure
The request body is a standard JSON object. You must include the model and input fields. The voice field is required.
```json { "model": "tts-1", "input": "Your text here", "voice": "nova", "response_format": "mp3", "speed": 1.0 } ```
Response handling
A successful response returns the audio binary directly in the body with a 200 OK status. Failed requests return a JSON error object with a code and message.
If synthesis fails, you are not charged. Always check the HTTP status code before attempting to play the file in your vehicle's UI.
Using the OpenAI SDK
The NavVoce API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing integrations by simply adjusting the base URL. Instead of pointing to OpenAI’s servers, your SDK client directs requests to https://api.cph2699.info/v1. This ensures compatibility with standard JSON bodies and response handling without requiring custom parsing logic.
You can continue using the official OpenAI SDKs for Python and JavaScript. The only change is configuring the client to use our API domain and your NavVoce key. This approach minimizes development time for automotive teams already familiar with the OpenAI ecosystem.
Changing base_url
Update your SDK client’s base URL to https://api.cph2699.info/v1. Ensure you replace the authorization header value with your NavVoce Bearer token (tts-...). This directs all speech synthesis requests to our infrastructure while maintaining the standard request shape.
Standard SDK compatibility
Our endpoint accepts the same parameters as the OpenAI speech endpoint. Models tts-1 and tts-1-hd work identically. You can pass voice presets, speed, and format options exactly as you would for OpenAI, making migration or parallel testing straightforward.
Code examples for Python/JS
In Python, initialize the client with base_url pointing to our API. Send a POST request with text, voice, and format. The SDK handles the JSON serialization. For JavaScript, the process is similar: set the base URL and call the speech method. Both environments return the audio file directly for playback in your in-car interface.
Example Python snippet: client = OpenAI(base_url="https://api.cph2699.info/v1", api_key="tts-your-key"). Then call `client.audio.speech.create(model="tts-1", voice="aria", input="Navigate to the nearest parking lot.")`. This returns the audio file data.
Request Parameters
The model field accepts tts-1 or tts-1-hd, which share the same engine and pricing. Your input text must not exceed 4,096 characters per request, a constraint that shapes how you structure navigation prompts for clarity.
Model selection (tts-1, tts-1-hd)
Both model values use identical synthesis engines and cost $0.01 per 1,000 characters. Choose based on your bandwidth or storage needs, as the audio quality remains consistent between them.
Voice presets (8 options)
Select from eight licensed voices optimized for in-car listening. Female presets include Aria (warm narrator), Nova (bright), Luna (soft storyteller), and Sage (calm instructional). Male options are Felix (energetic promo), Milo (friendly), Atlas (neutral news), and Orion (deep documentary).
- Aria: Warm, clear narrator
- Nova: Bright, upbeat
- Luna: Soft, storytelling
- Sage: Calm, instructional
- Felix: Energetic, promo
- Milo: Friendly, conversational
- Atlas: Neutral, news
- Orion: Deep, documentary
Speed control (0.25–4.0)
Adjust the speed parameter between 0.25 and 4.0 to match cabin noise levels or driver attention spans. Standard speed (1.0) generates roughly 25 characters per second, providing a natural rhythm for navigation instructions.
Response Formats
NavVoce returns audio as a binary blob in the response body, ready for direct playback or storage in your vehicle’s infotainment cache. Choose the format that best fits your network bandwidth and hardware decoding capabilities.
MP3 support
MP3 is the default and most compatible format for web and mobile integration. It offers a good balance between file size and quality.
- Default response format
- Broad player compatibility
- Efficient bandwidth usage
WAV support
WAV provides uncompressed, high-fidelity audio ideal for high-end in-car audio systems. Use this when preserving the exact audio waveform is critical for your sound processing pipeline.
Opus, FLAC, PCM options
Opus offers superior compression for low-bandwidth connections. FLAC provides lossless compression for archival quality without file size bloat. PCM returns raw linear audio data for immediate processing.
- Opus: Superior compression for low bandwidth
- FLAC: Lossless compression
- PCM: Raw data stream

Rate Limits and Queues
Understanding rate limits ensures your in-car voice interfaces remain responsive during peak usage. Our API processes requests sequentially, meaning high-volume generation may experience slight delays. This behavior is normal and designed to maintain audio quality without overloading the engine.
We also track usage to help you manage your key’s throughput effectively. Knowing your limits helps you plan batch jobs for navigation instructions or infotainment prompts without unexpected interruptions.
60 requests per minute
Each API key is limited to 60 requests per minute. This limit applies to the POST /v1/audio/speech endpoint. If you exceed this, you will receive a 429 Too Many Requests error. Plan your speech generation accordingly to avoid interruptions in your user experience.
- Limit: 60 requests/minute per key
- Endpoint: POST /v1/audio/speech
- Error: 429 Too Many Requests
10 requests before top-up
New keys start with a lower limit of 10 requests per minute. This applies until you make your first top-up. Once you add funds via USDT, the limit increases to the full 60 requests per minute. This allows you to test the API before committing to higher volumes.
- Initial limit: 10 requests/minute
- Trigger: First top-up
- Result: Limit increases to 60 requests/minute
Queue processing behavior
Requests are processed one after another. Under heavy load, a request may wait in a queue before synthesis begins. This ensures each audio file is generated with full quality. Typical speed is roughly real-time (25 characters per second), but queueing can add slight delays during peak times.
- Sequential processing
- Queueing under load
- Real-time speed estimate: 25 chars/sec
Handling Long Texts
Navigation instructions and infotainment prompts often exceed the single-request character limit. To deliver seamless audio for longer texts, you must split the input into chunks of up to 4096 characters and concatenate the resulting audio files.
This approach ensures reliable synthesis without truncation. While individual short phrases take a few seconds, long texts typically generate at roughly real-time speed, producing about 25 characters of text per second of audio.
4096 character limit
Each API request accepts a maximum of 4096 characters, including spaces and punctuation. If your navigation script or dialogue tree exceeds this length, the request will fail. You must handle the splitting logic in your client code before sending the data to the endpoint.
Splitting ensures that each chunk is processed efficiently. Since requests are handled sequentially, keeping chunks within this limit prevents unnecessary queuing delays for subsequent audio segments.
Splitting and joining audio
Divide your text into segments no longer than 4096 characters. Send each segment as a separate POST request to the speech endpoint. Once you receive the audio file for each chunk, concatenate them in order to create the final audio stream.
This method maintains continuity for users listening to detailed navigation directions. Ensure your audio player handles the transition between chunks smoothly to avoid audible gaps that might distract the driver.
- Count characters carefully, as spaces and punctuation count toward the 4096 limit.
- Maintain the original order of chunks when concatenating the audio files.
- Handle network errors per chunk; failed requests are refunded but do not stop other chunks.
Real-time speed estimation
Under typical load, generation speed is roughly real-time, producing approximately 25 characters of text per second of audio. This allows you to estimate playback duration accurately for your in-car interface.
Be aware that during high traffic, requests may wait in a queue. This can delay the start of audio playback slightly, but the total generation time for long texts remains close to the real-time ratio.
Error Codes and Responses
When your synthesis fails, you receive a standard HTTP error code along with a JSON body explaining the cause. Common issues include invalid API keys, exceeding the 4096 character limit per request, or unsupported language scripts. Each response includes a clear error message to help you adjust your payload immediately.
Crucially, if a request fails during synthesis, you are not charged. The credit is returned to your balance automatically, ensuring you only pay for successfully generated audio files.
Common error types
400 Bad Request: Invalid JSON or missing fields.
401 Unauthorized: Expired or incorrect Bearer token.
429 Too Many Requests: Exceeded 60 requests per minute limit.
- Check your input length (max 4096 chars).
- Verify your API key is active.
- Ensure the requested voice supports the specified language.
Failed request refunds
Synthesis failures trigger an immediate, full refund of the character cost. You do not need to manually claim these credits; they reappear in your account balance within minutes.
Debugging tips
Log the exact error message and timestamp. Verify that your language parameter matches the text script if it is not English. Use the GET /v1/voices endpoint to confirm available voices for your target language before sending bulk requests.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. A neutral tone works best for factual updates, while warmer tones suit conversational interactions.
23 languages
Any voice speaks any of these languages.
