Documentation for Text-to-Speech API Integration

By NavVoice editorial team · Updated 2026-11-19

This documentation guides automotive product teams in integrating NavVoce’s text-to-speech API into navigation and infotainment systems. You will find concrete examples for generating natural-sounding speech in 23 languages, optimized for clear in-car listening. We cover authentication, SDK integration, and parameter tuning to help you build reliable voice interfaces.

You will learn how to structure requests, handle responses, and manage long texts by splitting and joining audio segments. The guide also details rate limits, error handling, and response formats like MP3 and WAV. Use these specifications to implement seamless voice features that meet the specific needs of modern vehicle dashboards.

Documentation for Text-to-Speech API Integration

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

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

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

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

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

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

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

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

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

Rate Limits and Queues

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

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

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

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. Python documentation
  3. LibriVox public-domain audiobooks
  4. Node.js documentation
  5. TRON developer hub: TRC-20
  6. ISO 639 language codes
  7. FFmpeg documentation
  8. curl documentation
  9. IETF RFC 7845: Ogg Opus
  10. Tether (USDT)
  11. openai-node on GitHub
  12. LibriTTS-R corpus (OpenSLR 141)

More on this site