Quickstart Guide: Integrate Text-to-Speech into Your Podcast Workflow

By Podcast Voice Lab editorial team · Updated 2026-11-18

This guide helps podcast developers integrate our text-to-speech API into their production workflows. You will learn how to generate professional narration from text using eight distinct voices, suitable for shows, intros, and ads. We cover authentication, request parameters, and response formats with concrete examples.

You can use the official OpenAI SDKs by adjusting the base URL, or send standard HTTP requests. We explain rate limits, character constraints, and best practices for splitting longer scripts. This documentation is designed to get your first audio file generated quickly and reliably.

Quickstart Guide: Integrate Text-to-Speech into Your Podcast Workflow

Frequently asked questions

What SDKs are supported?

We do not provide an official SDK of our own. You can use the OpenAI SDK or plain HTTP requests. The OpenAI SDKs work by changing the base URL to our API endpoint. This allows you to use familiar libraries and code structures without needing a custom client.

Can I use the OpenAI SDK with this API?

Yes, the official OpenAI SDKs work with our API. You simply need to change the base URL to https://api.playli789.com/v1 and use your site-specific key. This compatibility allows you to use the same request shape as the OpenAI speech endpoint for seamless integration.

How do I set the base URL?

Set your base URL to https://api.playli789.com/v1. This endpoint handles POST requests for audio generation and GET requests for voices and models. Ensure your Authorization header includes your Bearer token starting with 'tts-...' to authenticate your requests correctly.

What is the maximum text length per request?

The maximum input text length is 4096 characters per request. If your script exceeds this limit, you must split the text into parts of up to 4096 characters. You then generate audio for each part and join the resulting audio files together.

How do I handle texts longer than 4096 characters?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate request to the speech endpoint. Once you receive the audio files for all parts, join them sequentially. This ensures the entire script is converted without hitting the character limit.

What format is returned by default?

The API returns audio in the format you specify in the request. Supported formats include mp3, wav, opus, flac, and pcm. If you do not specify a format, the API uses mp3 by default, but it is best practice to explicitly define your preferred output format.

How do I specify a language?

Include the optional 'language' field with an ISO code in your request body. If omitted, the API guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always set the language field to ensure correct voice synthesis.

Does the API support streaming audio?

No, the API does not support streaming, WebSocket, or real-time partial audio. You send a request and receive the complete audio file in the response. This synchronous approach is suitable for generating full episodes or ads where immediate streaming is not required.

What happens if the API is slow?

Requests are processed one after another, so under load a request may wait in a queue. Typical speed is roughly real time, but short phrases take a few seconds. If the API is busy, your request will simply wait until it is processed.

Can I use custom speeds?

Yes, you can adjust the speed between 0.25 and 4.0. This allows you to speed up narration for ads or slow it down for detailed explanations. The speed parameter is included in the JSON body of your POST request to the speech endpoint.

How do I detect errors in the response?

Check the HTTP status code and response body for error details. Failed requests are free, and the charge is returned in full if synthesis fails. Inspect the response for specific error messages to understand why a request failed, such as invalid parameters or rate limits.

Is there a webhook for completion?

No, there is no webhook for completion. The API is synchronous, meaning you receive the audio file directly in the response. You do not need to set up a webhook to know when generation is complete, as the response contains the final audio data.

How do I rotate my API key?

You can issue a new API key at any time from your account dashboard. When a new key is issued, the old one stops working immediately. This ensures that only your current active key is used for authentication, maintaining security for your podcast production workflow.

What is the character limit for the free trial?

The free trial provides $0.50 of credit, which equals about 50,000 characters. This credit is valid for 7 days when you sign in with Google. Accounts created with email and password start without this trial credit, so consider using Google for the initial trial.

First request

curl

curl https://api.playli789.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.playli789.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.playli789.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 podcast narration workflow by authenticating requests with a unique API key. This key links your generation requests to your account balance, ensuring accurate billing for every character synthesized.

API Key Usage

Obtain your key on the /get-api-key/ page. Use it for all API calls to distinguish your voice generations from other users.

Header Format

Include the key in the HTTP header as Authorization: Bearer tts-.... Ensure no extra spaces are included in the token string.

Key Rotation

Generate a new key anytime via your dashboard. The previous key becomes invalid immediately, providing instant security if your key is exposed.

Endpoint Overview

Sound wave illustration for: Endpoint Overview

Our API exposes three primary endpoints for generating and managing podcast audio assets. The core speech endpoint accepts text and parameters to return audio files, while the voices and models endpoints provide metadata about available synthesis options.

Speech Endpoint

Send a POST request to /v1/audio/speech with your JSON payload to generate audio. This is the primary interaction point where you define the model, input text, voice, and output format. The endpoint returns the audio file directly in the response body.

Voices Endpoint

Query GET /v1/voices to retrieve a list of all available voice presets, their associated languages, supported formats, and pricing details. This allows you to dynamically update your podcast interface with the latest voice options without hardcoding values.

Models Endpoint

Use GET /v1/models to verify the available model IDs, such as tts-1 and tts-1-hd. Both models use the same underlying engine and price, but this endpoint confirms the current configuration for your integration.

Endpoint Overview

Request Parameters

Sound wave illustration for: Request Parameters

Configure your speech generation by defining the text content, selecting a voice preset, and adjusting the playback speed. Each request processes up to 4,096 characters, so longer scripts should be split before submission.

Input Text

Provide the script text in the input field. Spaces and punctuation count toward the 4,096 character limit per request.

Voice Selection

Choose from eight presets like aria for narration or atlas for news. Every voice supports all 23 languages; if the language field is omitted, the system guesses based on the script.

Speed Control

Set the speed parameter between 0.25 and 4.0 to adjust pacing. Use lower values for detailed explanations or higher values for fast-paced ad reads.

Response Formats

Sound wave illustration for: Response Formats

Every audio response is a complete audio file that your application can save directly to disk. The API returns the audio file with the correct MIME type, ensuring seamless integration with your podcast hosting pipeline or playback engine.

You choose the format via the response_format parameter. Selecting the right format balances file size, compatibility, and audio fidelity based on whether you are storing assets or playing them to listeners.

MP3 Output

MP3 is the default and most widely supported format for podcast distribution. It offers excellent compression with minimal loss, making it ideal for web delivery and mobile apps where bandwidth matters. Files are typically small enough to cache efficiently on client devices.

Use MP3 when you need broad compatibility across all podcast players and social media platforms. The bitrate is optimized for speech, preserving clarity while keeping file sizes low for faster uploads and downloads.

  • Default format for most use cases
  • Highly compatible with all podcast apps
  • Optimized file size for web delivery

WAV Output

WAV provides uncompressed, lossless audio that preserves every detail of the synthesized voice. This format is ideal if you plan to do further editing, mixing, or mastering in a Digital Audio Workstation (DAW) before publishing.

Choose WAV when audio fidelity is critical for your production quality. The files are larger than MP3, so consider your storage costs and upload bandwidth when generating high-volume content.

  • Lossless quality for post-production
  • Ideal for editing and mixing
  • Larger file sizes than MP3

Other Formats

The API also supports Opus, FLAC, and PCM. Opus offers high-quality compression suitable for modern protocols. FLAC provides lossless compression, reducing file size without sacrificing quality. PCM returns raw audio data, useful for specific low-level processing needs.

Select these formats based on your specific technical requirements. Opus is great for efficient delivery, while FLAC and PCM serve niche workflows where lossless data is mandatory.

  • Opus: efficient streaming
  • FLAC: lossless compression
  • PCM: raw audio data

Code Examples

Sound wave illustration for: Code Examples

These examples demonstrate how to integrate our text-to-speech API into your podcast production pipeline. Each snippet handles the standard request structure, ensuring you can generate audio files for intros, narration, or ads with minimal code.

The examples use the OpenAI-compatible SDKs, requiring only a base URL change. This allows you to leverage familiar libraries while accessing our specific voices and pricing structure.

cURL Example

Use this command to generate speech instantly. Replace YOUR_API_KEY with your key from /get-api-key/.

```bash curl https://api.playli789.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Welcome to the show.", "voice": "nova", "response_format": "mp3"}' \ --output intro.mp3 ```

Python SDK

Install openai and configure the base URL to point to our API. This works with the official OpenAI Python package.

```python from openai import OpenAI client = OpenAI(base_url="https://api.playli789.com/v1", api_key="YOUR_API_KEY") with client.audio.speech.create(model="tts-1", voice="aria", input="Hello listeners.", response_format="mp3") as response: response.stream_to_file("episode.mp3") ```

JavaScript SDK

Initialize the client with the correct base URL. The SDK handles the file writing automatically.

```javascript import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.playli789.com/v1', apiKey: 'YOUR_API_KEY' }); const audio = await client.audio.speech.create({ model: 'tts-1', voice: 'felix', input: 'Ad break starting now.', response_format: 'mp3' }); ```

Code Examples

Error Handling

Sound wave illustration for: Error Handling

Handling errors correctly ensures your podcast production pipeline stays smooth without dropping episodes or wasting credits. Our API returns standard HTTP status codes to help you debug issues quickly, whether you are generating intros or full episode narration.

Understanding these responses helps you maintain consistent audio output even during high-volume generation periods or when network conditions fluctuate.

Common Errors

The API returns clear error messages for invalid inputs. If you exceed the 4096 character limit or select an unsupported voice, you will receive a 400 Bad Request. Ensure your JSON body matches the required schema exactly.

  • 400 Bad Request: Invalid parameters or format.
  • 401 Unauthorized: Missing or invalid API key.
  • 429 Too Many Requests: Rate limit exceeded.
  • 500 Internal Server Error: Temporary service issue.

Rate Limits

You are limited to 60 requests per minute per API key. New accounts without a top-up start with a lower limit of 10 requests per minute. These limits prevent abuse and ensure fair usage for all podcast publishers.

  • Standard limit: 60 requests/minute.
  • New account limit: 10 requests/minute.
  • Limits reset every 60 seconds.

Retry Logic

For transient errors like 500 or 429, implement exponential backoff. Do not retry 400 errors as they will fail again. Always check the error message details to determine if the issue is with your input or our service.

Retrying failed requests is free if the synthesis failed, but successful requests consume your character quota.

Limits and Quotas

Sound wave illustration for: Limits and Quotas

Understanding your usage limits helps ensure consistent audio generation for your podcast episodes. Our system balances performance with fairness, so knowing the boundaries prevents unexpected interruptions during high-volume production runs.

Requests Per Minute

Each API key is limited to 60 requests per minute. Before your first top-up, this limit drops to 10 requests per minute.

Character Limits

You can send up to 4,096 characters per request. Spaces and punctuation count toward this limit. For longer scripts, split the text into smaller chunks.

Queue Behavior

Requests are processed sequentially. Under heavy load, your request may wait in a queue before synthesis begins. This ensures stable performance for all users.

Limits and Quotas

Best Practices

Sound wave illustration for: Best Practices

Optimizing your podcast production workflow requires managing character limits and language detection carefully. By splitting long scripts and setting explicit language codes, you ensure consistent audio quality and avoid unexpected synthesis failures.

Handling audio files efficiently allows you to assemble seamless episodes without manual editing overhead. This approach keeps your API usage predictable and your final deliverables professional.

Text Splitting

Each API request accepts up to 4,096 characters. For longer monologues or detailed show notes, divide your script into chunks of this size. This prevents truncation and ensures each segment is synthesized cleanly.

Language Codes

While the API guesses language from Latin script (defaulting to English), always set the language parameter for non-English texts. This avoids mispronunciations in languages like Spanish, French, or German, ensuring natural delivery for your audience.

Audio Joining

Since requests are processed sequentially, concatenate the returned audio files to form your final episode. Use standard audio libraries to merge the segments, creating a continuous listening experience that matches your original script structure.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Captivating audio storytelling transforms passive listeners into devoted subscribers, driving sustained growth for forward-thinking publishing houses today.

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. OpenAI API reference: create speech
  4. ISO 639 language codes
  5. Tether (USDT)
  6. openai-node on GitHub
  7. IETF RFC 7845: Ogg Opus
  8. LibriVox public-domain audiobooks
  9. W3C WAI: making audio and video accessible
  10. curl documentation
  11. openai-python on GitHub
  12. MDN: Web Speech API

More on this site