API Documentation for Voice Assistant TTS

By Predictz Voice editorial team · Updated 2026-11-18

This documentation outlines the integration process for Predictz Voice’s text-to-speech API, designed specifically for startups developing voice assistants and chatbots. You will find precise specifications for the JSON request structure, supported parameters, and authentication methods required to generate natural-sounding audio files programmatically.

The guide details how to configure the OpenAI-compatible SDKs, manage rate limits of 60 requests per minute, and handle common status codes. It includes concrete code examples in Python and Node.js, along with curl commands for rapid testing, ensuring your voice interface maintains consistent quality across 23 languages and 8 licensed voices.

API Documentation for Voice Assistant TTS

Frequently asked questions

How do I get my API key?

Sign up on the /get-api-key/ page using Google or email and password. Your account page displays your active API key, balance, and usage statistics. You can issue a new key at any time, which immediately invalidates the previous one.

Which SDK should I use?

There is no official SDK of our own. Use the official OpenAI SDKs or plain HTTP requests. The API endpoint shape matches the OpenAI speech endpoint, allowing you to simply change the base URL to point to our service for compatibility.

Can I use the OpenAI Python SDK?

Yes. The request shape is identical to the OpenAI speech endpoint. You can use the official OpenAI Python SDK by configuring the base URL to https://api.getpredictz.com/v1 and providing your API key in the authorization header.

How do I change the base URL?

Configure your SDK or HTTP client to use https://api.getpredictz.com/v1 as the base URL. This allows you to use standard OpenAI SDKs by pointing them to our endpoint while maintaining the same request structure for generating audio files.

What is the maximum input length?

The maximum input length is 4096 characters per request. For longer texts, you must split the text into parts of up to 4096 characters, generate audio for each part, and join the resulting audio files manually in your application.

Does the API support streaming?

No. The API does not support streaming, WebSocket connections, or real-time partial audio delivery. You send a POST request and receive the complete audio file in the response. Requests are processed sequentially, so latency depends on queue load.

How do I handle rate limits?

The limit is 60 requests per minute per key, or 10 per minute before your first top-up. If you exceed this, requests may queue or fail. Monitor your usage on the account page and implement retry logic with exponential backoff.

What happens if the server is down?

There is no SLA or uptime guarantee. If synthesis fails, the charge is returned in full. Request metadata is kept for billing, but generated audio is not stored. You should implement error handling to retry failed requests after a delay.

Can I use custom headers?

Yes, you can include custom headers in your HTTP requests. The only required header is Authorization: Bearer tts-... for authentication. Other headers like Content-Type are standard for JSON POST requests and can be adjusted according to your client library.

Is JSON the only request format?

Yes, the API expects a JSON body for the POST request. The body must include fields like model, input, voice, and response_format. The structure matches the OpenAI speech endpoint, so standard JSON serialization libraries work directly without additional formatting steps.

How do I specify a voice?

Include the voice field in your JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. You can also optionally specify a language ISO code to guide synthesis, though the API guesses it if omitted.

Can I generate multiple voices at once?

No. Each request generates audio for a single voice. To use multiple voices, you must send separate requests for each voice. You can then join the resulting audio files in your application to create a multi-voice output.

Do I need to close the connection?

If using plain HTTP, close the connection after receiving the response to free resources. SDKs typically handle this automatically. Since there is no streaming, you do not need to manage persistent connections or WebSocket states for standard text-to-speech requests.

Are there any required headers?

Yes, you must include the Authorization header with your Bearer token: Authorization: Bearer tts-... . The Content-Type header should be set to application/json for POST requests. No other headers are strictly required, but standard HTTP headers may be used as needed.

First request

curl

curl https://api.getpredictz.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.getpredictz.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.getpredictz.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 and keys

Sound wave illustration for: Authentication and keys

Access the /get-api-key/ dashboard to generate your unique API key. The interface displays your active key, current balance, and usage statistics alongside a ready-to-use cURL example for immediate testing.

Generate API key in dashboard

Generate API key in dashboard

Sign up via Google or email on the dashboard page to receive your key. The system issues one active key per account, which you can find directly in the user interface.

  • Access key generation via /get-api-key/
  • Supports Google or email signup
  • One active key per account

Bearer token authorization

Bearer token authorization

Include your key in the request header as Authorization: Bearer tts-.... This standard method ensures your API calls are authenticated against your specific account balance.

  • Use Authorization: Bearer header
  • Format: tts-<your_key>
  • Standard HTTP authentication

One active key per account

Only one key remains active at any time. Issuing a new key immediately invalidates the previous one, ensuring simple credential management for your voice assistant infrastructure.

  • Single active key per account
  • New key invalidates old immediately
  • Simplifies credential rotation

Endpoint structure

Sound wave illustration for: Endpoint structure

The API exposes three primary endpoints for integration. The core synthesis endpoint handles audio generation, while metadata endpoints provide information on available voices and models. All requests use standard HTTP methods and JSON payloads, ensuring compatibility with existing TTS workflows.

POST /v1/audio/speech

Send text to generate audio files. This endpoint accepts JSON bodies with model selection, input text, voice presets, and optional parameters like speed and format. Responses return the audio file directly.

GET /v1/voices list

Retrieve the full catalog of 8 voice presets and their supported languages. This endpoint helps you verify available options for your chatbot’s personality without making synthesis requests.

  • List all 8 voice presets (e.g., Aria, Nova, Felix).
  • View supported languages and default formats.
  • Check per-voice pricing details.

GET /v1/models info

Get details about the underlying TTS models. Currently, both 'tts-1' and 'tts-1-hd' use the same engine and pricing, allowing flexible model selection based on your quality needs.

Request body parameters

Sound wave illustration for: Request body parameters

The TTS endpoint accepts a JSON body containing the text to synthesize and configuration parameters. The model field determines the engine quality, while input carries the source text string. You must configure the voice to select one of the eight licensed presets and can adjust speed between 0.25 and 4.0 to fit your voice assistant's pacing.

Model selection (tts-1)

Select either tts-1 or tts-1-hd for synthesis. Both models use the same underlying engine and pricing tier, so the choice depends solely on your audio quality preference rather than cost differences. The API processes requests sequentially, so model choice affects audio fidelity but not queue position.

Input text limit

Each request accepts up to 4,096 characters in the input field. Spaces and punctuation count toward this limit. For longer content, split the text into chunks, synthesize each part, and join the resulting audio files. Short phrases may take a few seconds to generate, while longer texts approach real-time speed.

Voice and speed settings

Choose from eight voices like aria for narration or atlas for news. Set the language parameter to an ISO code (e.g., en, de, ja) to ensure correct pronunciation; otherwise, the system guesses based on the script. Adjust speed from 0.25 to 4.0 to optimize latency for your chatbot interface.

  • 8 licensed voices available
  • Speed range: 0.25–4.0
  • Optional ISO language code
  • Latin script defaults to English

Response formats

Sound wave illustration for: Response formats

The API returns audio data directly in the HTTP response body, allowing immediate playback or storage. You select the desired format via the response_format parameter in your request. Supported formats include MP3, WAV, OPUS, and FLAC, catering to different bandwidth and quality needs for your voice assistant.

MP3 output

MP3 is the default format, offering a good balance between file size and audio quality. It is ideal for most web-based voice interfaces where bandwidth efficiency matters. The encoded stream plays seamlessly in standard browsers and media players.

WAV output

WAV provides uncompressed audio. Use this format when you need lossless quality for post-processing or specific voice assistant hardware that requires PCM data. Note that WAV files are significantly larger than MP3s.

OPUS and FLAC options

OPUS offers efficient compression for low-bandwidth environments, while FLAC provides lossless compression for archival purposes. Choose OPUS for efficient transfer in constrained networks, or FLAC if you need lossless quality without the large file size of WAV. Both are valid options in the response_format field.

Error handling and status codes

Sound wave illustration for: Error handling and status codes

Understanding HTTP status codes helps you debug integration issues efficiently. Our API returns standard codes to indicate success, authentication failures, or rate limit breaches. Always check the response body for a descriptive error message that explains the exact cause of the failure.

Most errors are client-side and resolvable by validating your request parameters or refreshing your API key. We do not guarantee uptime, so transient network issues may also trigger unexpected responses; implement exponential backoff in your retry logic for robustness.

400 Bad Request

This error indicates that the server could not process the request due to client-side errors, such as missing required fields, invalid JSON structure, or exceeding the 4096 character limit for the input field. Review the error message in the response body to identify the specific validation failure and correct your payload before retrying.

  • Check that model and input fields are present.
  • Ensure input does not exceed 4096 characters.
  • Verify that voice matches one of the 8 presets.
  • Confirm response_format is one of mp3, wav, opus, flac, or pcm.

401 Unauthorized

A 401 status means your API key is missing, invalid, or has been revoked. Ensure your Authorization header includes the correct Bearer token. If you issued a new key from the dashboard, the old key stops immediately. Regenerate your key if necessary and update your configuration.

Note that failed synthesis requests are free, but authentication failures do not consume your balance. Verify that your key starts with tts- and is active in your account settings.

  • Ensure header format: Authorization: Bearer tts-...
  • Check if a new key was issued, invalidating the old one.
  • Verify key is active in the dashboard.

429 Rate Limit Exceeded

This code appears when you exceed 60 requests per minute per key. If your account has not yet topped up, the limit is 10 requests per minute. The API queues requests under load, but sustained high volume will trigger this error. Wait for the rate limit window to reset before retrying.

Implement exponential backoff in your client code to handle 429s gracefully. Monitor your usage in the dashboard to anticipate limits, especially when processing long texts that require multiple split requests.

  • Limit: 60 requests/minute after top-up.
  • Limit: 10 requests/minute before first top-up.
  • Implement exponential backoff for retries.
  • Check dashboard for real-time usage stats.
Error handling and status codes

Rate limits and throttling

Sound wave illustration for: Rate limits and throttling

Predictz Voice enforces a strict rate limit of 60 requests per minute per API key. This cap applies to the synthesis endpoint and ensures stable performance for your voice assistant infrastructure. Monitoring your usage dashboard helps you stay within these boundaries during peak traffic.

60 requests per minute

The standard limit is 60 requests per minute for active accounts. This allows for consistent audio generation without overwhelming the processing queue. Exceeding this threshold triggers a 429 Too Many Requests error.

  • Limit: 60 requests/minute per key
  • Applies to all synthesis endpoints
  • Exceeded requests return HTTP 429

10 requests before top-up

New accounts or those without recent top-ups are restricted to 10 requests per minute. This lower limit ensures fair resource distribution during trial periods. Once you add USDT credit, the limit increases to the standard 60 requests/minute immediately.

  • Pre-top-up limit: 10 requests/minute
  • Standard limit: 60 requests/minute
  • Limit updates after USDT top-up

Queue behavior under load

Requests are processed sequentially. During high load, your synthesis job may enter a queue before processing begins. This can increase latency, especially for longer texts. Short phrases typically complete within a few seconds, but busy periods may introduce delays.

  • Sequential processing model
  • Queuing occurs during high load
  • Latency varies with queue depth

Code examples with OpenAI SDK

Sound wave illustration for: Code examples with OpenAI SDK

Integrate Predictz Voice into your chatbot using the official OpenAI SDKs. Since our API mirrors the standard speech endpoint, you only need to adjust the base URL and provide your API key.

This approach allows startups to leverage existing Python or Node.js client libraries without writing custom HTTP parsers, ensuring consistent audio generation across voice interfaces.

Python SDK example

Install the OpenAI Python library and initialize the client with your base URL.

Use the audio.speech.create method to generate MP3 or WAV files from text inputs.

  • pip install openai
  • from openai import OpenAI
  • client = OpenAI(base_url="https://api.getpredictz.com/v1", api_key="tts-...")
  • response = client.audio.speech.create(model="tts-1", voice="nova", input="Hello world", response_format="mp3")

Node.js SDK example

Initialize the OpenAI client with the custom base URL for Predictz.

Call the speech creation function to receive binary audio data directly.

  • npm install openai
  • const { OpenAI } = require("openai");
  • const openai = new OpenAI({ baseURL: "https://api.getpredictz.com/v1", apiKey: "tts-..." });
  • const response = await openai.audio.speech.create({ model: "tts-1", voice: "nova", input: "Hello" });

Base URL configuration

Set the base URL to https://api.getpredictz.com/v1 in your SDK configuration.

This directs all requests to our TTS endpoint while maintaining standard parameter structures.

Curl command examples

Sound wave illustration for: Curl command examples

The following examples demonstrate basic integration patterns using curl. These commands assume you have already generated a Bearer token via the dashboard.

Each request sends text to the speech endpoint and returns an audio file directly to your terminal or local storage.

Basic synthesis request

Send a simple text string to the default voice. The response body contains the raw audio bytes, which you can redirect to a file.

This command uses the aria voice and defaults to MP3 format. Replace YOUR_API_KEY with your actual credential.

  • curl -X POST https://api.getpredictz.com/v1/audio/speech \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"model": "tts-1", "input": "Hello world", "voice": "aria"}' \ --output speech.mp3

Speed adjustment command

Adjust the playback speed using the speed parameter. Values range from 0.25 to 4.0, with 1.0 being normal speed.

This example doubles the speed for efficient voice-over production.

  • curl -X POST https://api.getpredictz.com/v1/audio/speech \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"model": "tts-1", "input": "Fast narration", "voice": "nova", "speed": 2.0}' \ --output fast_speech.mp3

Language specific request

Explicitly set the language code to ensure correct pronunciation, especially for non-English Latin script texts.

This request forces French synthesis regardless of input text script.

  • curl -X POST https://api.getpredictz.com/v1/audio/speech \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"model": "tts-1", "input": "Bonjour", "voice": "luna", "language": "fr"}' \ --output french_speech.mp3

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This allows a single voice identity to maintain brand consistency across global markets without needing to retrain or swap voice assets for each new region.

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

More on this site