Frequently asked questions
What is the base_url for the OpenAI SDK?
Set the base_url to https://api.pandacina.info/v1. This allows you to use the official OpenAI SDKs by simply pointing them to our API endpoint. The request shape matches the OpenAI speech endpoint, ensuring seamless integration for developers already familiar with that ecosystem without needing a custom client library.
How do I set the authorization header?
Include the header Authorization: Bearer tts-... where the value is your unique API key. You can find this key on your /get-api-key/ dashboard page. Each account holds one active key; issuing a new one immediately invalidates the previous one, so update your apps accordingly to avoid authentication errors.
Which audio formats are recommended for car apps?
We support mp3, wav, opus, flac, and pcm. For navigation apps, mp3 or opus are ideal due to their small file size and efficient decoding, which reduces latency and bandwidth usage. Use wav or flac if you need uncompressed lossless audio for specific playback systems, though pcm is also available.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key (10 per minute before the first top-up). If you exceed this, subsequent requests will wait in a queue or fail. Since requests are processed sequentially, under load you may experience delays. Monitor your usage via the dashboard to stay within limits.
Can I use the SDK for iOS apps?
Yes. Since we use the standard OpenAI SDK request shape, you can use any standard HTTP client or the OpenAI SDK in your iOS app by changing the base_url. There is no proprietary iOS SDK required. You simply make POST requests to the speech endpoint with your API key and parameters.
How do I handle long route descriptions?
Split your text into parts of up to 4096 characters. Generate audio for each part separately, then join the resulting audio files. This ensures you stay within the character limit per request. Our typical speed is roughly real-time, so long texts will take time to generate but will play seamlessly.
What is the character limit per request?
Each request can process up to 4096 characters of text. This includes spaces and punctuation. If your route description exceeds this limit, you must split the text into smaller chunks, generate audio for each chunk, and concatenate the audio files in your application to create a continuous narration stream.
Do I need to install a specific library?
No. You can use the official OpenAI SDKs by changing the base_url, or use plain HTTP requests. There is no proprietary library required. Standard HTTP clients in any language can POST JSON to the endpoint and receive the audio file directly, making integration straightforward across all platforms and languages.
How do I detect errors in the response?
Check the HTTP status code and the JSON response body for error messages. Failed requests are free, and the charge is returned in full. If synthesis fails, the API will return an error status. You should implement retry logic for transient errors and monitor your dashboard for usage and error rates.
Can I change the voice mid-request?
No. Each request generates audio for a single voice specified in the voice field. To change voices, you must make separate requests for each segment of text with the desired voice parameter. You can then join the resulting audio files in your app to create a varied narration experience.
Is the API compatible with Android?
Yes. The API is platform-agnostic and works with any HTTP client. You can use standard Android networking libraries like OkHttp or Retrofit to send POST requests to the speech endpoint. Simply set the base_url and include your API key in the authorization header to receive audio files for your app.
How do I set the speed parameter?
Include the speed field in your JSON body with a value between 0.25 and 4.0. The default speed is 1.0. Adjusting this parameter allows you to make the narration faster or slower to match the pacing of your navigation instructions. Values outside this range will result in an error.
What is the default language if not specified?
If the language field is not set, the system guesses the language from the script. Latin script text defaults to English. For non-English Latin-script text, you should explicitly set the language parameter to ensure correct pronunciation. Supported languages include Arabic, Chinese, English, French, German, Spanish, and others listed in our docs.
Can I use the same key for multiple apps?
Yes, one active key per account can be used across multiple applications. However, all apps share the same rate limit of 60 requests per minute. If you run multiple apps concurrently, they will compete for this quota. Monitor your usage closely to ensure you do not exceed the per-key limit.
First request
curl
curl https://api.pandacina.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.pandacina.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.pandacina.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 |
Getting Your API Key
To begin integrating PandaTTS into your navigation app, visit the /get-api-key/ page to create your account. You can register using your Google account for immediate access to a free trial credit of $0.50, or use an email and password, which starts with a zero balance. This step establishes the identity required to generate your unique authentication token.
Once registered, you will receive a single active API key that authorizes all requests to the endpoint. This key is tied to your account’s usage limits and billing balance. Keep it secure, as it is the only credential needed to send text-to-speech requests for turn-by-turn directions or route narration.
Sign up on the /get-api-key/ page
Navigate to the registration page to initialize your developer account. The process takes seconds and requires no credit card. If you use Google sign-in, you immediately receive $0.50 in trial credit, equivalent to roughly 50,000 characters, valid for seven days. Email-based accounts start without trial funds.
Generate a key via Google or email
During registration, choose your preferred authentication method. Google sign-in provides instant access and trial credit. Email registration requires a password setup but offers standard account creation. Each account maintains one active key; issuing a new one instantly invalidates the previous key, so store your current key securely after generation.
- Google OAuth: Instant access, includes $0.50 trial credit
- Email + Password: Standard registration, no initial credit
- Single active key per account
- New key invalidates the old one immediately
View your key in the dashboard
After signing up, the dashboard displays your API key, current balance, and usage statistics. You can copy the key directly from this interface for use in your application’s configuration. The dashboard also shows your remaining characters and request history, helping you monitor usage as you test voice synthesis for navigation prompts.
- API Key display with copy button
- Current balance and trial status
- Usage history and character count
- Direct link to documentation
First API Request with curl
Generating audio for turn-by-turn instructions requires a simple HTTP POST request. This section demonstrates the most direct way to verify your integration using the command line, ensuring your key and endpoint are configured correctly before building into your app.
You will send a JSON payload containing the text to speak, the selected voice, and the desired audio format. The API returns the binary audio data directly in the response body, which you can save or play immediately.
Basic curl command example
Use this command to test the endpoint. Replace YOUR_API_KEY with your actual key. The response will be the raw audio file, which you can redirect to a file like response.mp3.
- `curl -X POST https://api.pandacina.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 response.mp3`
Setting the Authorization header
Every request must include the Authorization: Bearer tts-... header. Your API key is generated on the /get-api-key/ dashboard. If the key is invalid or expired, the API returns a 401 Unauthorized error immediately.
Sending a short navigation prompt
For navigation, keep inputs under 4096 characters. A prompt like "Turn left in 200 meters" works well with the 'nova' voice for bright, clear instructions. You can adjust the speed parameter if the voice speaks too slowly for fast traffic conditions.
Using the OpenAI SDK
To integrate PandaTTS into your navigation app, start by installing the official OpenAI SDK in your project. This library provides the necessary tools to handle HTTP requests efficiently, ensuring your app can communicate seamlessly with our TTS engine without writing custom networking code from scratch.
Install the official OpenAI SDK
Install the latest version of the OpenAI SDK using your preferred package manager. This ensures compatibility with the JSON request format we use, allowing you to leverage existing community examples for navigation apps.
Set base_url to our API endpoint
Configure the SDK’s base_url to point to https://api.pandacina.info/v1. This redirects all standard speech requests to our infrastructure while maintaining the familiar SDK structure. Ensure your authentication header uses your unique tts-... key.
Use the same request shape as OpenAI
Send your navigation prompts using the standard POST /v1/audio/speech structure. Pass your text, selected voice (e.g., atlas for news-style directions), and desired format. The SDK handles the serialization, so you focus on route logic while the API returns the audio file.
Supported Audio Formats
Choose the right audio format for your navigation app’s playback engine. MP3 offers broad compatibility across mobile and in-vehicle systems, while WAV provides uncompressed quality for high-fidelity playback. Other options include Opus, FLAC, and PCM for specific use cases.
MP3 for mobile compatibility
MP3 is the default choice for most navigation apps due to its wide support across Android and iOS devices. It balances file size and audio quality effectively for turn-by-turn instructions.
WAV for high-quality playback
WAV delivers uncompressed audio, ensuring the clearest possible voice output. This is ideal for premium in-vehicle systems where audio fidelity is prioritized over bandwidth constraints.
Opus, FLAC, and PCM options
Opus offers excellent compression for low-bandwidth scenarios. FLAC provides lossless compression for archival or high-end audio needs. PCM delivers raw, uncompressed audio data for direct playback without decoding overhead.
Rate Limits and Throttling
Understanding rate limits is critical for navigation apps that send frequent turn-by-turn instructions. Our API enforces strict per-key limits to ensure stable performance during peak usage. Knowing these thresholds helps you design robust retry logic and avoid unexpected interruptions in voice guidance.
Rate limits are calculated per API key, not per application instance. If you rotate keys, each key has its own independent limit. This allows you to scale request volume by managing multiple keys, provided you monitor usage across all active keys.
60 requests per minute per key
Once your account is funded, you can make up to 60 requests per minute. This limit applies to the POST /v1/audio/speech endpoint. Exceeding this limit will result in a 429 Too Many Requests error. Failed requests do not count toward this limit, ensuring you are not penalized for temporary network issues or invalid inputs.
To stay within this limit, monitor your usage via the dashboard. If you are generating audio for multiple devices, ensure each device uses a distinct API key or share a single key carefully to avoid hitting the aggregate limit.
- Limit: 60 requests/minute per key
- Applies to: POST /v1/audio/speech
- Exceeded status: 429 Too Many Requests
10 requests per minute before top-up
Free trial accounts and accounts without a top-up are limited to 10 requests per minute. This lower limit ensures fair usage while you evaluate the service. If you exceed this limit, your requests will be queued until the next minute window opens.
Top-ups are processed automatically via USDT on the TRON network. Once the transfer is confirmed, your limit increases to 60 requests per minute immediately. No manual verification is required, allowing you to resume high-volume generation quickly.
- Trial/No Top-up: 10 requests/minute
- Top-up: increases to 60 requests/minute
- Automatic processing within minutes
Queue behavior under load
Requests are processed sequentially within the rate limit window. If you send multiple requests simultaneously, they are queued and processed one after another. This means that under high load, the time to receive audio may increase significantly.
For navigation apps, this queuing behavior is important for real-time instructions. If you send a new instruction while the previous one is still being synthesized, it will wait in the queue. Consider implementing exponential backoff in your client code to handle 429 errors gracefully.
Long texts are split into parts, each counting as a separate request. Ensure your split logic accounts for the rate limit to avoid overwhelming the API during route narration.

Handling Long Texts for Routes
For turn-by-turn instructions, long route narrations often exceed the 4096-character input limit. You must split the text into smaller chunks before sending individual requests to the API endpoint.
Split text into 4096 character parts
Divide your navigation script into segments that fit within the character limit. Each segment triggers a separate synthesis request, ensuring valid responses from the API.
Join audio files sequentially
The API returns individual audio files for each chunk. Your app must concatenate these files in the exact order of the original text to create a seamless audio stream for the driver.
Manage memory for long routes
Long routes generate multiple audio files. Process and play them sequentially rather than storing all files in memory simultaneously to avoid memory issues on mobile devices.
Error Codes and Responses
The API returns standard HTTP status codes to indicate request success or failure. A 200 OK response includes the audio file, while 4xx errors typically indicate authentication or input issues. 5xx errors suggest temporary server overload during high demand.
Failed synthesis requests are free, ensuring you are not charged for wasted compute. Understanding these codes helps you build robust error handling for turn-by-turn instructions without draining your API credit.
Common HTTP error codes
Use 401 Unauthorized when your API key is missing or invalid. Return 429 Too Many Requests if you exceed the 60 requests per minute limit. A 400 Bad Request indicates invalid JSON or unsupported parameters.
- 401: Invalid or missing Bearer token
- 429: Rate limit exceeded (check quota)
- 400: Invalid input format
Handling failed synthesis
If synthesis fails due to a server error, the request is free. You can retry the request without incurring additional charges. Failed responses include a JSON body with error details for debugging.
- No charge for failed requests
- Retry on 5xx errors
- Check error message for details
Debugging request issues
Verify your Authorization header format. Ensure text input is under 4096 characters. Check that the voice and language parameters are valid ISO codes.
- Check Bearer token format
- Limit input to 4096 chars
- Validate voice/language codes
Voice and Language Parameters
To generate natural-sounding turn-by-turn instructions, select from eight distinct voice presets that cover both male and female ranges. Options range from the warm, clear narration of Aria to the neutral, news-style delivery of Atlas, ensuring your audio matches the specific context of your app.
Always specify the ISO language code for non-English text, as the system defaults to English for Latin-script inputs. This prevents mispronunciation in mixed-language routes and ensures accurate synthesis across the 23 supported languages, including Arabic, Chinese, and Swahili.
Setting the voice parameter
Choose voices based on your app’s tone: Luna for soft storytelling, Felix for energetic promos, or Orion for deep documentary styles. All voices support any of the 23 languages, allowing consistent audio branding regardless of the spoken language.
- Aria (warm, clear narrator)
- Nova (bright, upbeat)
- Luna (soft, storytelling)
- Sage (calm, instructional)
- Felix (energetic, promo)
- Milo (friendly, conversational)
Specifying language codes
Set the language field to the ISO code (e.g., de for German, ja for Japanese). Without this, Latin text defaults to English, which may cause incorrect pronunciation for other languages using the Latin alphabet.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Adjusting speed from 0.25 to 4.0
Adjust the speed parameter between 0.25 and 4.0 to optimize for clarity or brevity. Faster speeds reduce latency for quick alerts, while slower rates improve comprehension for complex route details. Note that speed affects generation time, impacting real-time responsiveness.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. If your app targets users who value aesthetic experience alongside navigation accuracy, these presets offer a distinct advantage.
23 languages
Any voice speaks any of these languages.
