API Documentation for Transport Voice Generation

By Paisita editorial team · Updated 2026-11-19

This documentation provides the technical specifications for integrating the Paisita Voices text-to-speech API into transport announcement systems. It details the request structure, authentication methods, and voice selection parameters required to generate consistent audio updates for large, multilingual teams. The guide covers all essential endpoints and response formats, ensuring straightforward deployment without enterprise overhead.

Designed for engineers and system administrators managing mixed-language regions, this page outlines the exact JSON body structure and supported models. You will find concrete examples for cURL and Python integration, along with specifics on rate limits, audio formats, and error handling. Use this reference to implement reliable, character-based voice generation for your transport infrastructure.

API Documentation for Transport Voice Generation

Frequently asked questions

Do I need to install a specific SDK to use this API?

No proprietary SDK is required. You can use standard HTTP libraries or the official OpenAI SDK by changing the base URL to https://api.paisita.info/v1. The request shape matches the OpenAI speech endpoint, allowing immediate integration with existing codebases without installing additional vendor-specific packages.

Can I use the official OpenAI SDK with this endpoint?

Yes. The API accepts the same request shape as the OpenAI speech endpoint. By configuring the OpenAI SDK with the base URL https://api.paisita.info/v1 and your Paisita API key, you can utilize the official SDK for seamless integration without modifying your core logic.

What is the maximum character limit per request?

Each request supports up to 4096 characters of input text. For longer announcements, split the text into parts of this size and join the resulting audio files. This ensures consistent processing and allows you to handle extensive route information or detailed safety instructions efficiently.

Does the API support real-time streaming of audio?

No, the API does not support real-time streaming, WebSockets, or partial audio delivery. It processes requests sequentially and returns the complete audio file upon completion. For large transport fleets, this means buffering the full response before playback, which is standard for announcement systems.

How do I specify the language for non-English text?

Include the optional language field with the ISO code in your JSON body. If omitted, the system guesses the language, defaulting to English for Latin script. For non-English Latin-script text, explicitly setting the language ensures accurate synthesis and prevents mispronunciation in multilingual regions.

Is the base URL different for the free trial?

No, the base URL remains https://api.paisita.info/v1 regardless of your account status. The free trial provides $0.50 of credit for 7 days when signing in with Google, but the API endpoint and request structure are identical to paid accounts using the same key.

What happens if I exceed the 60 requests per minute limit?

Requests are processed sequentially, so under load a request may wait in a queue. The rate limit is 60 requests per minute per key.

Are SSML tags supported for pronunciation control?

No, SSML tags are not supported. The API accepts plain text input up to 4096 characters. Pronunciation is controlled by the selected voice preset and language code. For specific pronunciation needs, you may need to adjust the input text spelling to match the desired audio output.

Can I request audio in FLAC format for higher quality?

Yes, you can specify flac in the response_format field. Available formats include mp3, wav, opus, flac, and pcm. FLAC provides lossless quality suitable for archival or high-fidelity announcement systems, though it requires more bandwidth compared to compressed formats like MP3 or Opus.

How do I handle rate limits in a large transport fleet?

Each API key is limited to 60 requests per minute. To handle a large fleet, distribute requests across multiple keys or implement client-side queuing to smooth out bursts. Since requests are processed sequentially, batching announcements or staggering schedules can help stay within the per-key rate limits.

Is the API key tied to a specific IP address?

No, the API key is not tied to a specific IP address. One active key is issued per account, and it can be used from any location. You can issue a new key at any time, which immediately invalidates the previous one, allowing easy rotation.

Do I need to manage expiration for my API key?

No, API keys do not expire. You can issue a new key at any time from your dashboard, which immediately stops the old key. This allows you to rotate keys for security without worrying about expiration dates or service interruptions during the transition.

Can I send text in Arabic without specifying the language code?

Yes, the system guesses the language from the script. If language is not set, it is guessed from the script. However, for Latin-script languages other than English, you must set the language field to ensure correct synthesis.

What is the response format for a successful request?

A successful request returns the generated audio file in the specified format (mp3, wav, opus, flac, or pcm). The response includes the binary audio data, allowing immediate playback or storage. Failed requests return no charge and typically include an error message in the JSON body.

First request

curl

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

The API uses standard Bearer token authentication. Include your unique key in the request header as Authorization: Bearer tts-.... This key authorizes all synthesis requests against your account balance.

Bearer token format

Bearer token format

Your key is a string starting with tts-. It must be passed exactly as shown in the header. Any deviation in the prefix or spacing may result in a 401 Unauthorized response.

Key rotation process

Key rotation process

You can issue a new key at any time via your dashboard. The new key becomes active immediately, and the previous key stops working at once. This allows seamless replacement without service interruption.

Single active key limit

Each account holds only one active key at a time. Generate a new key to invalidate the old one. This ensures clear attribution of usage to a single credential for billing and security purposes.

Endpoint: Speech Synthesis

Sound wave illustration for: Endpoint: Speech Synthesis

The POST /v1/audio/speech endpoint accepts text input and returns synthesized audio files. It follows the standard OpenAI speech request shape, allowing you to use existing OpenAI SDKs by simply updating the base_url to https://api.paisita.info/v1. This ensures seamless integration for transport teams already familiar with common API patterns.

POST /v1/audio/speech

Send a JSON payload to this endpoint to generate audio. The request requires a valid Bearer token in the Authorization header. The system processes requests sequentially, so under high load, synthesis may wait in a queue before generating audio.

JSON body structure

The body must include the model (tts-1 or tts-1-hd), the input text (up to 4096 characters), and the voice preset. You may optionally specify the response format, speed (0.25–4.0), and language ISO code. All fields except input and model are optional; defaults are applied if omitted.

  • model: tts-1 or tts-1-hd
  • input: text string (max 4096 chars)
  • voice: one of 8 presets
  • speed: 0.25 to 4.0
  • language: optional ISO code

Response format options

The endpoint returns binary audio data in the requested format (mp3, wav, opus, flac, or pcm). Failed requests return an error JSON object and incur no charge. The audio file is delivered directly in the response body, with no streaming or partial chunks available.

Supported Voices and Models

Sound wave illustration for: Supported Voices and Models

The API offers two model variants, tts-1 and tts-1-hd, which use the identical underlying engine and pricing. The distinction lies solely in the model identifier; both models use the identical engine and pricing. Both models support the full range of voice presets and languages without performance penalties.

tts-1 and tts-1-hd models

Select tts-1 or tts-1-hd in the model field. Since the engine is identical, switching between them does not alter voice characteristics or language support, only the bitrate and file size of the resulting audio. This allows transport teams to optimize storage and bandwidth for high-frequency announcements while maintaining the same voice consistency across the fleet.

8 preset voice profiles

Eight distinct voice profiles are available, categorized by tone to suit different announcement contexts. Female voices include Aria for clear narration, Nova for upbeat updates, Luna for soft storytelling, and Sage for instructional guidance. Male options cover Felix for energetic promos, Milo for conversational tones, Atlas for neutral news delivery, and Orion for deep, documentary-style announcements.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion

Language-agnostic voice selection

Any of the eight voices can speak all 23 supported languages, including Arabic, Chinese, English, Hindi, Japanese, Spanish, and others. The system does not restrict voices to specific native languages, allowing a single voice profile to handle multilingual routes. If the language parameter is omitted, the system guesses the language from the text script, defaulting to English for Latin text.

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts plain text input with a strict maximum of 4096 characters per request. Spaces, punctuation, and special characters all count toward this limit. For announcements exceeding this length, split the text into sequential requests and join the resulting audio files.

The speed parameter allows adjustment between 0.25 and 4.0, enabling precise control over announcement pacing. This ensures clarity for large transport teams or diverse linguistic groups without requiring manual audio editing.

Input text limit (4096 chars)

Each synthesis request processes a maximum of 4096 characters. This constraint applies to the entire string, including spaces and punctuation. If an announcement is longer, divide the text into logical segments and concatenate the output audio files sequentially.

For large transport teams deploying updates across mixed-language regions, this limit requires careful segmentation of route announcements or safety instructions to ensure complete delivery without truncation.

  • Maximum length: 4096 characters per request.
  • Spaces and punctuation count toward the limit.
  • Split longer texts and join audio files manually.

Speed control (0.25–4.0)

Adjust the generation speed using the speed parameter, accepting values from 0.25 to 4.0. The default speed is 1.0.

Generation time scales with the speed setting, roughly matching real-time speech at 1.0.

Optional language ISO code

The language parameter accepts an ISO 639-1 code to explicitly set the output language. If omitted, the system guesses the language from the text script, defaulting to English for Latin script. For non-English Latin text, always specify the language to prevent mispronunciation.

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. Any voice can speak any of these languages.

  • Explicitly set language for non-English Latin text.
  • Defaults to English if Latin script is detected.
  • Supported: 23 languages including Arabic, Chinese, French, Spanish, and others.

Rate Limits and Throttling

Sound wave illustration for: Rate Limits and Throttling

Rate limits are enforced per API key to ensure stable delivery of transport announcements. The system processes requests sequentially, which means that during high-volume periods, synthesis jobs may wait in a queue before processing begins.

This sequential handling ensures consistent audio quality but requires careful planning for large-scale deployments. Under load, requests are processed one after another, so longer texts may experience slight delays depending on current server congestion.

60 requests per minute

Each API key is limited to 60 requests per minute. This limit applies to all synthesis attempts, regardless of text length. If you exceed this threshold, subsequent requests will receive a 429 Too Many Requests error until the window resets.

Queue behavior under load

Requests are processed in the order they are received. If the system is busy, your request will wait in a queue. This can increase latency for long texts, which require multiple chunks to be synthesized and joined.

Limits for new accounts

New accounts start with a reduced limit of 10 requests per minute. This applies until the first top-up is processed. After a minimum $5 USDT transfer is confirmed, the limit increases to the standard 60 requests per minute.

Rate Limits and Throttling

Error Handling and Responses

Sound wave illustration for: Error Handling and Responses

The API returns standard HTTP status codes to indicate request outcomes. A 200 OK response delivers the audio binary, while 4xx errors indicate client-side issues such as invalid keys or malformed JSON. 5xx codes signal temporary server-side problems during synthesis.

Standard HTTP status codes

Use 200 for successful synthesis. 400 errors cover bad request bodies or unsupported parameters. 401 indicates an invalid or revoked API key. 429 means you have exceeded the 60 requests per minute limit.

Free retry on failure

If synthesis fails, the charge is returned in full. You may retry the request immediately without incurring additional costs. This ensures you only pay for successfully generated audio.

Error message structure

Errors return a JSON object with an error field containing a message string. Use this data to debug integration issues quickly.

  • Response includes error code and descriptive message
  • Character count remains unchanged on failure
  • Retry immediately for transient server errors

Code Examples

Sound wave illustration for: Code Examples

Integrate Paisita Voices into your transport announcement system using standard HTTP or the OpenAI Python SDK. Configure the base URL to point to our API endpoint and pass your bearer token for authentication.

Send text payloads up to 4096 characters to receive synthesized audio in formats like MP3 or WAV. Use the provided examples to handle requests for multilingual announcements across mixed-language regions.

cURL command example

Use cURL to test your integration directly from the terminal. Replace YOUR_API_KEY with your active key and adjust the voice and language parameters as needed.

  • Replace 'YOUR_API_KEY' with your token from /get-api-key/.
  • Set 'aria' as voice and 'en' as language for English announcements.

OpenAI SDK with base_url

Leverage the official OpenAI SDK by overriding the base URL. This allows you to use familiar methods while routing requests to our infrastructure.

  • Set base_url to https://api.paisita.info/v1.
  • Use the same authentication header format as OpenAI.

Python integration snippet

A simple Python script demonstrates sending a request and saving the audio response. This approach is suitable for backend services generating announcements for transport fleets.

  • Install the openai package.
  • Handle the binary response to save as an audio file.

Audio Formats and Delivery

Sound wave illustration for: Audio Formats and Delivery

The API delivers synthesized audio as a binary response in one of five supported formats: MP3, WAV, OPUS, FLAC, or PCM. Specify the desired format via the response_format parameter in your JSON request body. The service does not store generated audio; the file is returned directly in the HTTP response for immediate use or local storage by your transport fleet management system.

MP3, WAV, OPUS, FLAC, PCM

Select the format that best balances file size and quality for your distribution network. PCM is available for raw audio processing.

Binary response data

The response body contains the raw audio bytes corresponding to the requested format. Headers indicate the content type. Ensure your client application handles binary data correctly to prevent corruption during transmission to vehicle endpoints or central servers.

No streaming support

This service does not support WebSocket or real-time partial audio streaming. The entire audio file is generated and returned only after synthesis completes. For long texts split into 4096-character parts, you must request and join files sequentially or in parallel batches.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Her voice remains engaging without fatigue, making her suitable for comprehensive journey updates.

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. FFmpeg documentation
  3. W3C WAI: making audio and video accessible
  4. IETF RFC 7845: Ogg Opus
  5. curl documentation
  6. ISO 639 language codes
  7. OpenAI API reference: create speech
  8. Creative Commons Attribution 4.0
  9. openai-python on GitHub
  10. TRON developer hub: TRC-20
  11. Node.js documentation
  12. LibriTTS-R paper (arXiv 2305.18802)

More on this site