Developer Guide for NavAudio Text-to-Speech API

By NavAudio editorial team · Updated 2026-11-18

This documentation provides the technical reference for integrating NavAudio Systems’ text-to-speech API into automotive telematics and in-car entertainment infrastructure. It details the standard HTTP endpoints, authentication protocols, and request structures required for generating natural-sounding voice guidance for navigation alerts and media systems. The guide covers essential parameters for model selection, voice presets, and output formats, ensuring seamless compatibility with existing fleet management workflows.

The content is designed for engineering teams managing large-scale voice generation pipelines. It includes practical examples for cURL and OpenAI SDK integration, along with specific details on rate limits, error handling, and character constraints. By following these specifications, developers can reliably deploy consistent synthetic speech without managing additional infrastructure, ensuring consistent delivery for in-vehicle applications.

Developer Guide for NavAudio Text-to-Speech API

Frequently asked questions

What is the API endpoint URL?

The primary endpoint is POST https://api.playp333.com/v1/audio/speech. You send a JSON body containing the text, model, voice, and other parameters. This endpoint handles all speech synthesis requests. Additional endpoints include GET /v1/voices for metadata and GET /v1/models for model information. Use these endpoints to interact with the API.

How do I authenticate my requests?

Include your API key in the Authorization header using the Bearer scheme. The format is Authorization: Bearer tts-... . You receive one active key per account. If you issue a new key, the previous one stops immediately. Ensure your key is valid and associated with your NavAudio Systems account before sending requests.

Can I use the official OpenAI SDK?

Yes, the official OpenAI SDKs work with this API. You must change the base_url to https://api.playp333.com/v1 and use your NavAudio Systems key. The request shape matches the OpenAI speech endpoint. This allows you to integrate existing OpenAI-based codebases without significant refactoring, ensuring compatibility with your current development workflow.

What is the maximum text length per request?

The maximum input text length is 4096 characters per request. If your text exceeds this limit, you must split it into parts. Generate audio for each part separately and then join the resulting audio files. Spaces and punctuation count toward the character limit, so plan your splitting strategy accordingly to avoid truncation.

How do I specify the language?

You can specify the language using the optional language parameter with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always set the language parameter to ensure accurate synthesis. Supported languages include Arabic, Chinese, English, and others listed in the documentation.

What happens if I send a request with no voice?

The API requires a voice parameter. It is not optional. You must select one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, such as warm, bright, or neutral. If you do not specify a voice, the request will fail, and you will not be charged.

Can I stream the audio directly?

No, streaming is not supported. The API returns the complete audio file in the response after synthesis is finished. There is no WebSocket or real-time partial audio delivery. You must wait for the full response to receive the audio data. This ensures file integrity but means you cannot play audio incrementally during generation.

Is SSML supported for emphasis?

SSML is not supported. The API accepts plain text input only. You cannot use SSML tags for emphasis, pauses, or pronunciation adjustments. If you need specific pacing, you can adjust the speed parameter between 0.25 and 4.0. This simplifies the integration process but limits fine-grained control over the synthesized speech output.

How do I handle rate limits?

The rate limit is 60 requests per minute per key. Before the first top-up, the limit is 10 requests per minute. Requests are processed sequentially, so under load, your request may wait in a queue. If you exceed the limit, your requests will be delayed or rejected. Monitor your usage and implement retry logic with exponential backoff.

What audio formats are available?

You can choose from mp3, wav, opus, flac, and pcm formats. Specify the desired format using the response_format parameter in your request. Each format has different characteristics regarding file size and quality. Select the format that best suits your automotive telematics or in-car entertainment system requirements. All formats are generated from the same engine.

Do I need to install any specific libraries?

No specific libraries are required beyond standard HTTP clients or the OpenAI SDK. You can use the official OpenAI SDK or plain HTTP requests. The API uses standard JSON bodies and responses. This allows you to integrate the service into any programming language or environment that supports HTTP communication, reducing dependency overhead for your automotive software teams.

Can I use the same key for multiple projects?

Yes, you can use the same API key across multiple projects. The key is associated with your account, not a specific project. However, all projects share the same rate limits and balance. Monitor your total usage across all projects to ensure you stay within the 60 requests per minute limit and have sufficient credit.

How do I check the status of my requests?

Status is indicated by the HTTP response code and the response body. Successful requests return the audio file. Failed requests return an error message and are free, with the charge returned in full. You can also check your usage and balance on the /get-api-key/ page. Request metadata, including time and status, is kept for billing purposes.

What is the response time for synthesis?

Typical speed is roughly real time, generating about 25 characters of text per second of audio for long texts. Short phrases may take a few seconds. Requests are processed sequentially, so under load, a request may wait in a queue. Longer texts take longer to process due to the character-to-time ratio. Plan your infrastructure accordingly for large batches.

First request

curl

curl https://api.playp333.com/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.playp333.com/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.playp333.com/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

Authentication relies on a single active API key issued to your account. Include this key in the Authorization header as a Bearer token for all requests to https://api.playp333.com/v1. This ensures secure access for your automotive telematics integrations.

Use Bearer token in Authorization header

Use Bearer token in Authorization header

Include your key in every request using the standard header format: Authorization: Bearer tts-.... This method is compatible with standard HTTP clients and the OpenAI SDK when configured with our base URL.

One active key per account

One active key per account

Each account maintains exactly one active key. This simplifies credential management for large automotive teams, reducing the risk of stale credentials in production environments.

Revoke old keys instantly when issuing new ones

Issuing a new key immediately invalidates the previous one. This provides instant security control without waiting for session timeouts, ensuring precise access management for your in-car systems.

Endpoint Overview

Sound wave illustration for: Endpoint Overview

The NavAudio API provides three primary endpoints for integration. The primary generation endpoint accepts text and configuration parameters to return synthesized audio files. Two metadata endpoints allow your systems to discover available voice presets and engine details.

These endpoints ensure that automotive telematics systems can dynamically select appropriate voices for navigation alerts and media announcements based on current vehicle context or driver preference.

POST /v1/audio/speech for generation ['This endpoint accepts a JSON body containing the text input, voice selection, and audio format preferences. It returns the generated audio file directly in the response body, allowing immediate playback or storage in your telematics database.', 'The endpoint enforces a 4096-character limit per request. For longer navigation instructions, split the text into segments and concatenate the resulting audio files.'] ['Accepts model, input, voice, response_format, and speed parameters', 'Returns audio data in the specified format (mp3, wav, opus, flac, or pcm)', 'Supports optional language ISO code for accurate speech synthesis']

GET /v1/voices for preset details ['Retrieve a list of all available voice presets, including their unique identifiers, gender, and stylistic descriptors. This allows your application to map specific voice profiles to different navigation scenarios, such as using a calm voice for detailed directions and an energetic voice for promotional media.', 'Each voice is backed by licensed recordings and supports all 23 supported languages, ensuring consistent quality across global automotive fleets.']

GET /v1/models for available engine info ["Returns metadata about the underlying speech engines. Currently, both 'tts-1' and 'tts-1-hd' models are available, offering different quality tiers.", 'Use this endpoint to dynamically adjust model selection based on vehicle network conditions or user subscription tiers.']

Request Parameters

Sound wave illustration for: Request Parameters

The API requires precise configuration of the model, input text, and voice parameters to generate consistent audio for automotive telematics. Each request must adhere to strict character limits and supported preset definitions to ensure reliable synthesis within the in-car entertainment workflow.

Proper parameter selection directly impacts the resulting audio quality and processing time. Developers must select from the eight available voice presets, ensuring the tone matches the specific use case, whether it is navigation guidance or media alerts.

model: 'tts-1' or 'tts-1-hd'

Select 'tts-1' for standard generation or 'tts-1-hd' for high-definition audio. Both models use the same engine and pricing structure, allowing teams to switch without changing infrastructure. The choice depends on whether superior audio fidelity is required for specific alert types.

The model parameter determines the synthesis engine used. There is no performance difference in generation speed between the two options.

  • 'tts-1': Standard quality, standard price
  • 'tts-1-hd': High-definition quality, standard price
  • Same engine, same rate limits

input: text up to 4096 characters

The input field accepts plain text up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer navigation instructions or media descriptions, split the text into chunks and join the resulting audio files sequentially.

Generation speed is approximately real-time, averaging 25 characters of text per second of audio. Short phrases are processed quickly, while longer texts may enter a queue during high load, processing one request after another.

  • Maximum 4096 characters per request
  • Spaces and punctuation count as characters
  • Split longer texts and join audio files

voice: one of 8 available presets

Choose from eight licensed voice presets based on recordings from LibriTTS-R and LibriVox. Each voice has a distinct tone suitable for different automotive contexts, such as navigation, alerts, or media narration.

Voices are categorized by gender and tone. Female voices include Aria, Nova, Luna, and Sage. Male voices include Felix, Milo, Atlas, and Orion. All voices can speak any of the 23 supported languages.

  • 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

Response Formats

Sound wave illustration for: Response Formats

Selecting the correct response format ensures compatibility with your automotive infotainment stack and telematics middleware. The API returns audio data directly in the body of the response, allowing immediate ingestion by your playback engines without intermediate storage steps.

Each format balances bandwidth, latency, and fidelity requirements specific to in-vehicle networks. Choose based on your hardware’s decoding capabilities and the criticality of audio clarity for navigation instructions or alert systems.

mp3: compressed, widely supported

MP3 provides efficient compression with broad hardware support across modern vehicle head units. It minimizes bandwidth usage during high-volume generation while maintaining sufficient clarity for voice guidance.

Ideal for standard navigation prompts and media announcements where minimal latency is required during active driving.

  • Optimal for standard telemetry data streams
  • Low bandwidth consumption for in-car networks

wav: uncompressed, high quality

WAV delivers raw, uncompressed audio data, ensuring bit-perfect fidelity for critical alert systems. Use this format when your playback hardware requires lossless input or when verifying audio integrity.

Suitable for high-priority safety warnings where no decoding artifacts are acceptable.

  • Lossless fidelity for critical alerts
  • Low decoding latency for simple players

opus, flac, pcm: specialized use cases

Opus offers superior compression efficiency for bandwidth-constrained telematics links. FLAC provides lossless compression for archival or offline playback systems. PCM returns raw audio samples, suitable for direct hardware interface integration.

Select these formats only when your specific automotive audio pipeline requires their unique properties.

  • Opus: efficient for low-bandwidth telematics
  • FLAC: lossless archival storage
  • PCM: direct hardware integration

Quick Start with cURL

Sound wave illustration for: Quick Start with cURL

Send text to the speech endpoint using standard HTTP POST requests. The API accepts JSON payloads with voice selection and format preferences, returning binary audio data directly in the response body.

Basic command structure

Use curl to send a POST request to https://api.playp333.com/v1/audio/speech. Include your API key in the Authorization header and specify the model, voice, and input text in the JSON body.

Required headers and body

The request must include Authorization: Bearer tts-... and Content-Type: application/json. The body requires model (e.g., "tts-1"), voice (one of eight presets), and input (text up to 4096 characters).

  • Authorization: Bearer <your_key>
  • Content-Type: application/json
  • model: "tts-1" or "tts-1-hd"
  • voice: e.g., "nova"
  • input: "Navigate to next turn"
  • response_format: "mp3"

Example response handling

On success, the response contains the audio file in the requested format (mp3, wav, opus, flac, or pcm). Save the response body directly to a file for playback in your telematics system.

Quick Start with cURL

Integration with OpenAI SDK

Sound wave illustration for: Integration with OpenAI SDK

The NavAudio API is fully compatible with the official OpenAI Python and Node.js SDKs. By adjusting the client configuration, teams can leverage existing infrastructure and codebases without rewriting core integration logic. This approach minimizes development time for automotive telematics systems that already utilize standard TTS patterns.

Integration requires only a simple endpoint override. The request shape remains identical to the OpenAI speech endpoint, ensuring that parameter handling, error structures, and response parsing function exactly as expected. This compatibility allows large automotive teams to deploy consistent voice guidance across navigation and alert systems with minimal friction.

Set base_url to api.playp333.com/v1

Initialize the OpenAI client with your NavAudio API key and set the base_url to https://api.playp333.com/v1. This directs all SDK calls to our infrastructure while maintaining standard authentication headers. The key format remains Bearer tts-..., ensuring seamless credential management across your development and production environments.

No additional configuration is required for the SDK to recognize the new endpoint. The underlying HTTP transport handles the connection automatically. This flexibility is critical for automotive teams managing multiple in-car entertainment systems.

  • Set base_url to https://api.playp333.com/v1
  • Use standard Authorization: Bearer header
  • Maintain existing SDK client initialization

Use standard speech client methods

Call the standard speech.create() method (Python) or client.audio.speech.create() (Node.js) just as you would for OpenAI. Pass your API key, voice preset, and input text. The SDK handles the JSON serialization and HTTP POST request to the correct endpoint. Response parsing remains consistent, returning audio data in the specified format.

This method allows you to integrate NavAudio into existing navigation alert workflows without modifying the core speech generation logic. Teams can continue using familiar patterns for handling audio data or file writes.

  • Use standard speech.create() method
  • Pass voice, input, and format parameters
  • Handle response as standard audio data

Maintain same request shape

The request body uses the same fields: model ('tts-1' or 'tts-1-hd'), input, voice, response_format, and speed. You can adjust speed between 0.25 and 4.0 to match the pacing of navigation instructions. Language support is automatic, though you may specify an ISO code for non-English Latin-script text to ensure accurate pronunciation.

Since the request shape is identical, you can directly reuse OpenAI SDK examples. This reduces the learning curve for developers already familiar with the OpenAI ecosystem. The only difference is the endpoint, which is handled by the base_url configuration. This consistency ensures that code written for one TTS provider can be easily adapted for NavAudio with minimal changes.

  • Use standard request fields: model, input, voice
  • Adjust speed between 0.25 and 4.0
  • Optional language parameter for non-English text

Error Handling

Sound wave illustration for: Error Handling

The API returns standard HTTP status codes to indicate request outcomes. Understanding these responses allows your telematics system to handle failures gracefully without interrupting the user experience.

400: Invalid input or parameters

A 400 error indicates that the request body contains invalid data. Common causes include exceeding the 4096-character limit for the input field or providing an unrecognized voice preset.

  • Check character count before sending
  • Verify voice names against /v1/voices

401: Authentication failure

This error occurs when the Authorization header is missing or the Bearer token is invalid. Ensure your API key is correctly formatted and active.

  • Verify Bearer token format
  • Check key status in dashboard

429: Rate limit exceeded

You receive a 429 status if you exceed 60 requests per minute. Implement exponential backoff in your integration to handle queueing during high load periods.

  • Monitor requests per minute
  • Implement retry logic

Rate Limits and Queuing

Sound wave illustration for: Rate Limits and Queuing

The API enforces a strict limit of 60 requests per minute per active key. This cap ensures stable throughput for large automotive teams generating voice guidance at scale. New accounts start with a lower limit of 10 requests per minute until the first top-up is processed.

During periods of high demand, requests are processed sequentially. If the queue fills, subsequent requests wait until previous synthesis jobs complete. This guarantees consistent audio quality without concurrent processing bottlenecks.

60 requests per minute per key

Each API key is capped at 60 requests per minute. This limit applies uniformly regardless of model choice (tts-1 or tts-1-hd). Accounts must monitor usage to avoid interruptions in navigation audio streams.

New accounts begin with a 10 requests per minute limit. This threshold increases to 60 automatically within minutes after the first USDT top-up of at least $5 is confirmed on the TRON network.

  • Limit resets every 60 seconds.
  • Applies per API key, not per IP.
  • New accounts start at 10 req/min.

Queued processing during high load

Requests are processed in the order received. Under heavy load, synthesis may wait in a queue before generation begins. This sequential processing ensures deterministic output but increases latency during peak usage.

Developers should account for queue time when generating real-time alerts. Splitting long texts into smaller chunks can help maintain throughput, as each chunk requires a separate request.

  • Processing is sequential.
  • Latency increases under load.
  • No concurrent processing guarantee.

Real-time generation for short texts

Short phrases typically generate within a few seconds, approximating real-time performance. The system processes roughly 25 characters of text per second of generated audio. This speed is sufficient for most in-car notification use cases.

For longer texts, split input into 4096-character segments. Join the resulting audio files client-side. This approach maintains consistent quality and allows for better queue management during high-volume generation.

  • ~25 chars/sec generation speed.
  • Short texts take a few seconds.
  • Split long texts at 4096 chars.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. The navigation system provides accurate guidance for the entire fleet.

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. W3C WAI: making audio and video accessible
  3. Python documentation
  4. ISO 639 language codes
  5. Tether (USDT)
  6. IETF RFC 7845: Ogg Opus
  7. MDN: Web Speech API
  8. openai-python on GitHub
  9. Creative Commons Attribution 4.0
  10. openai-node on GitHub
  11. LibriTTS-R corpus (OpenSLR 141)
  12. curl documentation

More on this site