TTS API Docs: Integrate Text-to-Speech for Car Apps

By WayAudio editorial team · Updated 2026-11-18

This documentation helps indie car developers integrate high-clarity synthetic voices into navigation apps and dashboard interfaces. You will find concrete, step-by-step instructions for connecting WayAudio’s text-to-speech API to your in-cabin software. We cover authentication, request structures, and voice selection to ensure consistent, license-safe speech optimized for in-cabin listening.

The guide assumes you are building a car app and need reliable audio generation without complex infrastructure. You will learn how to configure the OpenAI SDK, handle audio formats like MP3 and OPUS, and manage rate limits or long-text splitting. All examples use real parameters from our API, so you can copy-paste and test immediately.

TTS API Docs: Integrate Text-to-Speech for Car Apps

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.playn777.com/v1. You use this endpoint for all requests, including POST /v1/audio/speech for synthesis and GET /v1/voices for metadata. This URL structure allows you to integrate the service directly into your car application’s backend or client-side logic without needing a separate gateway.

How do I authenticate with the API?

Authentication uses a Bearer token in the Authorization header. Include the header Authorization: Bearer tts-... with your unique API key. Each account has one active key at a time; issuing a new key immediately invalidates the old one, so ensure your car app updates its credentials promptly after a rotation.

Can I use the Python OpenAI SDK?

Yes, the official OpenAI SDKs work perfectly. Configure the SDK’s base_url to https://api.playn777.com/v1 and provide your WayAudio API key. This allows you to use standard Python libraries to call the speech endpoint without writing custom HTTP client code, simplifying integration for indie developers familiar with OpenAI’s ecosystem.

What is the maximum text length per request?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For navigation instructions longer than this, you must split the text into chunks, generate audio for each part, and join the resulting audio files in your application logic before playing them to the driver.

How do I set the voice language?

Pass the optional language field with an ISO code in your request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always specify the language to ensure accurate synthesis, as any voice can speak any of the 23 supported languages.

Does the API support SSML?

No, the API does not support SSML. You cannot use speech marks or prosody tags to control pacing or pronunciation. If you need specific timing, adjust the speed parameter between 0.25 and 4.0, or split your text manually to insert pauses by joining separate audio segments in your car app.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key. If you exceed this, the API returns a 429 Too Many Requests error. Short phrases may take a few seconds, and under load, delays increase. Failed requests remain free, but successful ones incur charges. Monitor your usage to avoid latency spikes during heavy navigation updates.

Is the API key case-sensitive?

Yes, the API key is case-sensitive. Ensure you copy it exactly from your dashboard at /get-api-key/. The key format is tts-.... Incorrect casing will result in authentication errors. Since only one key is active per account, verify you are using the current valid key issued to your WayAudio account.

Can I generate audio in multiple formats at once?

No, each request generates a single audio file in one format. Specify response_format as mp3, wav, opus, flac, or pcm. To get multiple formats, you must send separate requests for the same text. This allows your car app to choose the optimal format based on current network conditions or player capabilities.

How do I handle long navigation instructions?

Split text into parts of up to 4096 characters. Generate audio for each part using separate requests, then join the audio files in your application. This ensures reliable synthesis and avoids hitting character limits. The API processes requests sequentially, so plan your splitting logic to minimize latency during turn-by-turn directions.

Is the response format always MP3?

No, MP3 is just one option. You can choose mp3, wav, opus, flac, or pcm by setting the response_format field. WAV and FLAC offer lossless quality, while MP3 and OPUS are compressed. PCM provides raw audio data. Select the format that best fits your car app’s audio pipeline and storage constraints.

Do I need to handle audio streaming?

No, the API does not support streaming or WebSocket connections. You receive the complete audio file in the response after synthesis finishes. For short phrases, this takes a few seconds. Your car app must wait for the full file before playing it, as there are no partial audio chunks available.

How do I verify the audio is synthetic?

Every generated file contains an inaudible watermark marking it as synthetic speech. This watermark is embedded in the audio data itself. You do not need special tools to detect it; it is automatically included in all outputs from the tts-1 and tts-1-hd models, ensuring transparency for your users and compliance requirements.

What is the model name for HD audio?

Use tts-1-hd for high-definition audio. The standard model is tts-1. Both use the same engine and price ($0.01 per 1,000 characters). Choose tts-1-hd if your car app requires higher fidelity for dashboard interfaces, ensuring clear speech even in noisy cabin environments with premium audio systems.

First request

curl

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

Get your API key

Sound wave illustration for: Get your API key

Access the /get-api-key/ page on playn777.com to create your account. You can sign up instantly using your Google account or register with an email address and password. Each account is tied to this specific site and provides a single active API key for authenticating your requests.

Sign up with Google or email

Sign up with Google or email

Google sign-ups include a $0.50 trial credit valid for 7 days. Email-based accounts start without trial credit. Both methods generate a unique account per site, ensuring your navigation app’s integration is isolated and secure.

Locate key in dashboard

Locate key in dashboard

After signing up, the dashboard displays your API key immediately. It appears as a string starting with tts-. You can copy this key directly into your car app’s configuration or code. The dashboard also shows your current balance, trial status, and a ready-to-use cURL example for testing.

  • Key format: tts-...
  • Visible immediately after sign-up
  • Included in dashboard view

Issue new key if needed

You can generate a new API key at any time from the dashboard. Once issued, the old key stops working immediately. This allows you to rotate credentials securely without downtime for your navigation service.

First request with cURL

Sound wave illustration for: First request with cURL

Send your first synthesis request using cURL. Replace {API_KEY} with your unique key from the dashboard and {VOICE} with one of the eight available presets. The base URL points directly to the API endpoint for speech generation.

Base URL configuration

Configure your request to https://api.playn777.com/v1/audio/speech. Ensure the Authorization header includes Bearer {API_KEY}. This URL structure mirrors the standard OpenAI format, allowing direct integration with existing car app workflows.

JSON body structure

Construct the JSON body with model (tts-1 or tts-1-hd), input (text up to 4096 characters), voice, and response_format. You may optionally specify speed between 0.25–4.0 and language for precise control over synthetic speech output.

  • model: "tts-1" or "tts-1-hd"
  • input: Your navigation text string
  • voice: e.g., "atlas" or "nova"
  • response_format: "mp3", "wav", "opus", "flac", or "pcm"

Response handling

The API returns the audio file directly in the response body. Save this binary data to your car app’s local storage or play it to the dashboard speaker. Failed requests return a full refund of character credits.

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

Leverage the official OpenAI SDK to integrate speech synthesis into your car app with minimal code changes. The API maintains the standard request shape, allowing you to reuse familiar client structures while directing traffic to our cloud infrastructure.

Change base_url parameter

Point your SDK client to the WayAudio base URL: https://api.playn777.com/v1. This simple configuration swap enables the use of standard OpenAI libraries without requiring custom wrappers or new dependencies.

Keep standard client setup

Use your API key for authentication via the Authorization: Bearer header. Pass model, input, voice, and other parameters exactly as defined in the standard speech endpoint schema. No special headers or custom fields are needed.

Handle audio response

The SDK returns binary audio data directly. Write the response data to a local file or buffer. Ensure your car interface supports the requested response_format (e.g., mp3 or wav) for playback.

  • Supported formats: mp3, wav, opus, flac, pcm

Voice selection parameters

Sound wave illustration for: Voice selection parameters

Selecting the right voice ensures your navigation cues are clear and less fatiguing for drivers during long trips. You can choose from eight distinct presets, ranging from warm narrators to energetic promotional voices, all optimized for in-cabin listening.

The API lets you fine-tune delivery by adjusting speed and explicitly setting the language, preventing misinterpretation of non-English text in Latin script.

Choose from 8 presets

Each voice has a specific tone suited for different driving contexts. Use Atlas for neutral news updates or Orion for deep, documentary-style directions.

Available voices include Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. All support 23 languages regardless of the voice selected.

  • 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

Set speed between 0.25–4.0

Adjust the speed parameter to match driving conditions. Higher speeds (up to 4.0) help convey urgency in traffic alerts, while lower speeds (0.25–1.0) improve clarity for complex turn-by-turn instructions.

This range allows you to balance listening comfort with information density without distorting the voice quality.

Specify ISO language code

Always set the language parameter using an ISO code, especially for non-English Latin-script text. If omitted, the system guesses the language, defaulting to English for Latin script, which may cause errors in other languages.

Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.

Supported audio formats

Sound wave illustration for: Supported audio formats

For car apps, MP3 is the standard choice. It offers reliable playback across many Android and iOS in-car systems while keeping file sizes small. This ensures quick decoding and smooth navigation voice delivery.

MP3 for mobile efficiency

MP3 is the recommended format for most dashboard interfaces. It balances quality and size, ensuring that navigation prompts load quickly.

  • Default choice for general navigation prompts.
  • Broad compatibility with car infotainment systems.

OPUS for low bandwidth

Use OPUS when your app streams audio over cellular data. It provides high quality at lower bitrates, reducing data usage for users with limited plans. This is suitable for route updates sent over the network.

  • Optimal for cellular streaming.
  • Reduces data consumption for users.

WAV and FLAC options

WAV and FLAC are available for local caching or high-fidelity playback. These uncompressed or lossless formats ensure no audio degradation, which is useful for storing frequently used navigation instructions locally on the device. They are larger but guarantee exact reproduction of the synthetic voice.

  • WAV: Uncompressed, widely supported.
  • FLAC: Lossless compression for archival quality.
Supported audio formats

Rate limits and queuing

Sound wave illustration for: Rate limits and queuing

Rate limits protect the API's stability during high-volume navigation updates. Each API key supports a maximum of 60 requests per minute. This limit applies to all synthesis endpoints collectively.

60 requests per minute limit

The system processes requests sequentially, meaning complex audio generation may take longer than simple phrases. If you exceed 60 requests in a minute, the API returns a 429 Too Many Requests error. Plan your batch splits accordingly to avoid interruptions in navigation prompts.

10 requests before top-up

New accounts without a top-up are limited to 10 requests per minute. This ensures fair usage for trial users. Once you add funds via USDT (TRC-20), this limit increases to the standard 60 requests per minute.

Handling queue delays

Under load, requests may wait in a queue before processing begins. Typical speed is roughly real-time, but short phrases may take a few seconds. Implement exponential backoff in your client to handle temporary delays gracefully without dropping navigation cues.

Error handling and retries

Sound wave illustration for: Error handling and retries

Robust error handling ensures your navigation app remains responsive when the TTS service encounters issues. By correctly interpreting HTTP status codes and implementing exponential backoff, you prevent app freezes during temporary outages or billing pauses.

Common HTTP error codes

A 403 Forbidden indicates insufficient balance or an expired trial, requiring immediate top-up. A 429 Too Many Requests signals that you have exceeded the 60 requests per minute limit per key. Use the /v1/voices endpoint to verify voice availability if you receive a 400 Bad Request.

  • 401: Invalid or missing API key
  • 403: Insufficient balance
  • 429: Rate limit exceeded (60 req/min)

Retry logic for failures

Implement exponential backoff for 429 and 5xx errors. Wait 1 second, then 2, then 4 seconds before retrying. This prevents overwhelming the API during high load when requests are queued. Do not retry 400 or 403 errors as they require manual intervention.

Character limit errors

The API rejects inputs exceeding 4096 characters with a 400 error. Ensure your text preprocessing splits long navigation instructions before sending. Handle this gracefully by splitting the string in your client code rather than relying on server-side splitting.

Long text splitting strategy

Sound wave illustration for: Long text splitting strategy

For navigation instructions exceeding 4096 characters, split the input text into chunks of that length. Send each chunk as a separate POST request to the speech endpoint. This ensures every segment stays within the single-request limit.

Split at 4096 characters

Count every character, including spaces and punctuation. If a single instruction is longer, divide it precisely at 4096 characters. Do not exceed this limit, or the request will fail.

Join audio files sequentially

The API returns audio files for each chunk. Concatenate these files in the exact order they were requested. Play them sequentially in your car’s audio player to create a continuous voice output.

Manage memory usage

Download each audio file before requesting the next one if memory is limited. Process them in a loop rather than storing all files in RAM simultaneously. This keeps your app stable during long directions.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. A neutral vocal quality reduces cognitive load by removing subjective emotional cues.

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. LibriTTS-R corpus (OpenSLR 141)
  3. Tether (USDT)
  4. MDN: Web Speech API
  5. Python documentation
  6. openai-node on GitHub
  7. Creative Commons Attribution 4.0
  8. IETF RFC 7845: Ogg Opus
  9. TRON developer hub: TRC-20
  10. FFmpeg documentation
  11. ISO 639 language codes
  12. curl documentation

More on this site