Text-to-Speech API Documentation: Quickstart & Integration

By Linguicore editorial team · Updated 2026-11-18

This guide helps teams building synthetic speech datasets for machine learning integrate our text-to-speech API quickly. You will find clear examples for generating consistent, watermark-marked audio files in 23 languages, perfect for training your models without complex infrastructure.

We cover authentication, request parameters, and rate limits, including how to handle queues during peak loads. You can also see how to use the official OpenAI SDKs by simply changing the base URL, ensuring a smooth transition into your existing workflows.

Text-to-Speech API Documentation: Quickstart & Integration

Frequently asked questions

Do I need an OpenAI account?

No. You sign up directly on playzbzb.com using Google or email. We are not affiliated with OpenAI. The API mimics the OpenAI request shape, so you can reuse existing code by changing the base URL and using your Linguicore API key for authentication.

What is the base URL?

The API base URL is https://api.playzbzb.com/v1. You use this endpoint for all requests, including POST /v1/audio/speech, GET /v1/voices, and GET /v1/models. Ensure your SDK or HTTP client points to this domain to route requests correctly to our infrastructure.

Can I use the Python SDK?

Yes, the official OpenAI Python SDK works by setting the base_url to https://api.playzbzb.com/v1. Pass your API key in the Authorization header. Other SDKs like JavaScript or Go also work if you update the base URL and use our specific API key.

How do I handle long texts?

Split your input text into chunks of up to 4096 characters. Send each chunk as a separate request to the speech endpoint. Then, join the resulting audio files in your application. This ensures each request stays within the character limit and generates valid audio.

What is the character limit per request?

Each request supports up to 4096 characters in the input field. Spaces and punctuation count toward this limit. If your text exceeds this, you must split it into multiple requests. Each request generates a separate audio file that you can concatenate later.

Can I change the voice mid-stream?

No. The API does not support streaming or mid-stream changes. Each request generates a complete audio file for the provided text. To change voices, you must send a new request with the desired voice parameter. You can then stitch the audio files together.

Do you support streaming audio?

No. We do not offer streaming, WebSocket, or real-time partial audio. The API returns complete audio files once synthesis is finished. This simplifies integration for batch processing and dataset generation, as you receive the final file rather than managing stream buffers.

How do I get my API key?

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

What happens if I exceed the rate limit?

You are limited to 60 requests per minute per key (10 before the first top-up). Exceeding this may cause requests to queue or fail. Failed requests are free, so you are not charged for retries. Monitor your usage on the account dashboard to avoid delays.

Is the API RESTful?

Yes. It uses standard HTTP methods: POST for speech generation and GET for retrieving voices and models. Requests use JSON bodies, and responses return audio files or JSON metadata. This structure allows easy integration with any language or framework that supports RESTful HTTP calls.

Can I use the same key for multiple projects?

Yes, one active key per account can be used across multiple projects. However, all projects share the same rate limit of 60 requests per minute. If you need higher throughput, consider managing concurrency within your application logic.

Do you provide webhook notifications?

No. We do not provide webhook notifications. You must poll the API or rely on the synchronous response from the POST request. The API returns the audio file directly in the response, so webhooks are unnecessary for standard workflows.

How do I test the API?

Use the ready curl example on your account page. Send a POST request to /v1/audio/speech with a short text and your API key. You can also use the OpenAI SDK by changing the base URL. Check the response for the audio file or error details.

What is the response time?

Typical speed is roughly real time, about 25 characters per second. Short phrases take a few seconds. Requests are processed sequentially, so under load, you may experience queueing delays. Longer texts take longer to generate proportionally to their length.

First request

curl

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

Secure your API access with a simple Bearer token. Pass your key in the Authorization header as Bearer tts-... for every request to https://api.playzbzb.com/v1. This format ensures compatibility with standard HTTP clients and the OpenAI SDK.

Bearer token format

Bearer token format

Include your unique key in every API call. The token starts with tts- and identifies your account for billing and rate limiting.

API key generation

API key generation

Retrieve your key on the /get-api-key/ dashboard after signing in via Google or email. Each account holds one active key at a time.

Key rotation

Generate a new key anytime from your dashboard. The previous key stops working immediately, ensuring tight control over your synthetic speech dataset production pipeline.

Speech Endpoint

Sound wave illustration for: Speech Endpoint

The core of the API is the POST /v1/audio/speech endpoint. Send your text payload here to receive synthesized audio files, enabling your team to generate consistent synthetic speech datasets for machine learning training without managing complex infrastructure.

You control the output via a standard JSON body. Specify the model, voice preset, and format to match your dataset requirements. The API handles the synthesis, returning the audio directly in the response.

POST /v1/audio/speech

Send a POST request to this endpoint with your text and configuration parameters. The endpoint accepts texts up to 4096 characters per request, allowing you to split longer datasets into manageable chunks.

JSON request body

Structure your request with fields like model, input, voice, and response_format. You can also adjust speed between 0.25 and 4.0 or specify a language code if the script isn't clear.

  • model: "tts-1" or "tts-1-hd"
  • input: your text string
  • voice: one of the 8 presets
  • response_format: mp3, wav, opus, flac, or pcm
  • speed: 0.25–4.0
  • language: optional ISO code

Response format

The API returns the generated audio file directly in the response body. Each file carries an inaudible watermark marking it as synthetic speech, which helps identify dataset sources later.

Request Parameters

Sound wave illustration for: Request Parameters

To synthesize audio, you send a JSON payload to the speech endpoint. The request must include the text input, a chosen model, a voice preset, and the desired output format. You can optionally specify a language code to override automatic detection, which defaults to English for Latin-script text.

Model selection (tts-1, tts-1-hd)

Choose between "tts-1" and "tts-1-hd". Both use the same underlying engine and pricing, so your choice depends only on your quality preference. There is no functional difference in generation speed or voice variety between the two options.

Voice presets

Select from eight distinct voice presets tailored for consistent dataset generation. Female voices include Aria, Nova, Luna, and Sage, while male options offer Felix, Milo, Atlas, and Orion. Each voice supports all 23 available languages, allowing you to maintain consistent audio characteristics across multilingual training data.

  • 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

Speed control

Adjust the playback speed between 0.25 and 4.0 to fit your dataset’s timing requirements. Slower speeds can improve clarity for complex phonetic sequences, while faster speeds help reduce total generation time for large-scale data collection. The API processes requests sequentially, so extreme speed variations may slightly affect queue wait times.

Response Formats

Sound wave illustration for: Response Formats

The API returns binary audio data directly in the HTTP response body, allowing you to save files immediately. You control the file format via the response_format parameter, which determines the encoding and container structure of the generated speech.

MP3 output

MP3 is the default format, offering a good balance between file size and compatibility. It is widely supported across all major platforms and media players, making it ideal for general-purpose synthetic speech datasets.

WAV output

WAV provides uncompressed audio data. Use this format when you need high fidelity for training acoustic models.

OPUS and FLAC

OPUS offers superior compression efficiency for smaller file sizes while maintaining high quality. FLAC provides lossless compression, reducing storage costs without sacrificing audio quality. Both are suitable for archival or bandwidth-constrained environments.

Rate Limits

Sound wave illustration for: Rate Limits

Synthetic speech datasets require consistent throughput. Our API enforces a hard limit of 60 requests per minute per key to maintain stability for large-scale generation pipelines.

This cap ensures fair resource distribution across all teams using the same infrastructure for their ML training data.

Each request counts as one unit, regardless of text length or audio duration.

60 requests per minute

The standard rate limit allows 60 requests per minute. This supports steady batch processing for dataset creation.

Requests are processed sequentially. If you send 60 requests at once, they will be handled in order within the minute window.

  • Limit applies per API key.
  • Resets every 60 seconds.
  • Applies to all request types equally.

10 requests before top-up

New accounts without a top-up are limited to 10 requests per minute. This prevents excessive consumption of free trial credits.

Once you add USDT (TRC-20), the limit increases to the full 60 requests per minute immediately.

  • Applies to accounts with no balance.
  • Capped at 10 req/min.
  • Unlocks fully after first top-up.

Queue behavior

Requests exceeding the current minute’s quota are queued and processed in the next available window.

Longer texts may take more time to synthesize, but they still count as one request.

No data loss occurs; queued requests are processed automatically once capacity allows.

  • Requests are queued automatically.
  • No manual retry needed.
  • Processes in FIFO order.
Rate Limits

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

The API mimics the OpenAI speech endpoint structure, allowing teams to reuse existing OpenAI SDKs with minimal configuration. By simply adjusting the base URL, you can generate synthetic speech datasets without rewriting your integration logic.

This approach simplifies adoption for teams already familiar with OpenAI’s ecosystem, enabling rapid prototyping and consistent dataset generation for ML models.

Base URL configuration

Set your SDK’s base URL to https://api.playzbzb.com/v1 and include your API key in the Authorization: Bearer header. This single change directs requests to our TTS engine while preserving standard OpenAI request shapes.

SDK compatibility

The official OpenAI SDKs work seamlessly because the JSON body structure matches theirs. Use standard client initialization with the custom base URL to start generating audio files immediately.

  • Compatible with Python, Node.js, and other OpenAI SDK languages

Code examples

Here is a Python example using the OpenAI SDK to generate speech: ```python import openai client = openai.OpenAI(base_url="https://api.playzbzb.com/v1", api_key="tts-...") response = client.audio.speech.create(model="tts-1", voice="nova", input="Hello world") with open("speech.mp3", "wb") as f: f.write(response.content) ```

Error Handling

Sound wave illustration for: Error Handling

Our API uses standard HTTP status codes to signal success or failure during synthesis. A 200 OK response includes the audio binary, while 4xx errors indicate client-side issues like invalid parameters or missing authentication.

Understanding these codes helps you debug integration issues quickly. Most failures are immediate and clear, allowing your pipeline to handle errors gracefully without guessing the root cause.

HTTP status codes

We return standard HTTP codes to indicate request outcomes. Use 200 for successful synthesis, 400 for bad requests (e.g., invalid JSON or missing fields), 401 for authentication failures, and 429 when you exceed the rate limit. A 500 status indicates a temporary server issue.

  • 200: Success, audio data returned
  • 400: Bad Request, check your JSON body
  • 401: Unauthorized, verify your Bearer token
  • 429: Too Many Requests, wait before retrying
  • 500: Internal Server Error, try again later

Error messages

Each error response includes a JSON body with a clear message explaining the issue. For example, if your text exceeds 4096 characters, you will receive a specific error stating the limit was exceeded. These messages are designed to be actionable, helping you adjust your request parameters immediately.

Retry logic

For transient errors like 429 or 500, implement exponential backoff in your client. Since requests are processed sequentially during high load, a short pause often resolves queue delays.

Voices Endpoint

Sound wave illustration for: Voices Endpoint

Call GET https://api.playzbzb.com/v1/voices to retrieve the full catalog of available synthesis voices. The response lists each voice’s ID, gender, and supported languages, allowing your pipeline to dynamically select the optimal voice for each synthetic speech dataset.

GET /v1/voices

Send a standard authenticated GET request to the endpoint. The API returns a JSON object containing an array of voice objects, each defining the preset name, voice type, and available language codes.

List available voices

The endpoint returns eight presets: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. Each voice ID maps directly to the voice parameter in your speech requests, ensuring consistent audio characteristics across your generated datasets.

  • 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

Language support

All eight voices support 23 languages, including English, Spanish, German, French, Japanese, Korean, Chinese, Arabic, Hindi, Russian, Portuguese, Italian, Turkish, Polish, Dutch, Swedish, Danish, Norwegian, Finnish, Greek, Hebrew, Malay, and Swahili. You can optionally specify the ISO language code to ensure correct pronunciation, though the system also attempts automatic detection.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This ensures data provenance and prevents accidental mixing of human and synthetic samples during model training.

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. Python documentation
  3. OpenAI API reference: create speech
  4. Tether (USDT)
  5. LibriTTS-R corpus (OpenSLR 141)
  6. curl documentation
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. IETF RFC 7845: Ogg Opus
  9. LibriVox public-domain audiobooks
  10. openai-python on GitHub
  11. Creative Commons Attribution 4.0
  12. Node.js documentation

More on this site