Frequently asked questions
How do I get my API key?
Sign up on our /get-api-key/ page using Google or an email and password. Once registered, you will receive one active API key starting with 'tts-'. You can issue a new key at any time, which immediately invalidates the old one. The dashboard displays your key, balance, and usage statistics.
What is the maximum input length?
Each API request supports a maximum of 4096 characters for the input text. This limit includes spaces and punctuation. For longer scripts, you must split the text into chunks of 4096 characters or less, generate audio for each part, and then join the resulting audio files.
Can I stream the audio as it generates?
No, the API does not support streaming or WebSocket connections. You send a POST request to the speech endpoint and receive the complete audio file in the response. The audio is generated after the request is processed, so you must wait for the full file before playback.
Does the API support SSML tags?
No, the API does not support SSML tags, phoneme dictionaries, or custom pronunciation lexicons. You control pacing and tone by adjusting the speed parameter between 0.25 and 4.0, or by selecting one of the eight specific voice presets that match your desired narrative style.
How do I specify a specific language?
Include the optional 'language' field in your JSON body with the ISO code. If omitted, the system 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 accurate pronunciation across our 23 supported languages.
What happens if the request times out?
If synthesis fails for any reason, the charge is returned in full. Failed requests are free, so you are not billed for audio that does not generate successfully. This ensures you only pay for completed audio files delivered via the API response.
Can I use the same key on multiple servers?
Yes, each account has one active key that can be used across multiple servers or clients. You can issue a new key at any time, which immediately stops the previous one. This allows you to rotate keys easily if needed without changing your account setup.
Is the API rate-limited per IP or per key?
Rate limits are applied per API key, not per IP address. Each key is limited to 60 requests per minute, or 10 requests per minute before your first top-up. This allows you to scale usage across multiple servers as long as the total requests per key stay within limits.
How do I handle large scripts exceeding 4096 chars?
Split your script into parts of up to 4096 characters each. Send each part as a separate POST request to the speech endpoint. Once you receive the audio files for all parts, join them sequentially to create the final complete audio file for your podcast or narration.
Do I need to encode the input text?
Send the text as a standard JSON string in the 'input' field. The API handles the encoding internally. Ensure your text does not exceed 4096 characters. Spaces and punctuation count toward this character limit, so plan your splits accordingly to avoid truncation.
What is the 'tts-1-hd' model?
The 'tts-1-hd' model uses the same engine and pricing as 'tts-1'. Both models support the same eight voices and 23 languages. Choose 'tts-1-hd' when you need higher fidelity for professional podcast intros or narration without any change in cost or structure.
Can I request a specific audio format?
Yes, specify the 'response_format' field in your request. Supported formats include mp3, wav, opus, flac, and pcm. This allows you to choose the format for your workflow, whether you need compressed audio for web delivery or lossless formats for editing in your podcast production software.
How do I test the API before paying?
Sign in with Google to receive a free trial of $0.50 credit, valid for 7 days. This provides about 50,000 characters for testing. Accounts created with email and password start without trial credit. Use this credit to test voices, formats, and integration before topping up with USDT.
Is the documentation versioned?
The API uses a fixed version path: /v1/. The endpoint is POST https://api.playgb168.com/v1/audio/speech. The documentation covers the current stable release. We do not maintain multiple historical versions on the site; all requests should use the /v1/ path for compatibility with the latest features and pricing.
First request
curl
curl https://api.playgb168.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.playgb168.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.playgb168.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 | |
|---|---|
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 |
Authentication
Secure your API access by generating a unique key via the /get-api-key/ dashboard. You can authenticate using Google or an email account to receive a Bearer token prefixed with "tts-". This token grants you permission to send text-to-speech requests to the cloud API.
API Key Generation
Visit the /get-api-key/ page on playgb168.com to create your account. Upon signing in with Google or your email, the dashboard displays your active API key alongside your balance and character usage.
- Sign up via Google or email/password
- Key displayed on the dashboard immediately
- One active key per account
Bearer Token Usage
Include your key in the HTTP header as Authorization: Bearer tts-... for every request. The official OpenAI SDKs work seamlessly by pointing base_url to https://api.playgb168.com/v1.
Ensure the key remains secret, as it controls your billing and usage limits.
- Format:
Authorization: Bearer tts-<your-key> - Required for all POST and GET requests
Key Rotation
Generate a new key at any time from your dashboard. The previous key becomes invalid immediately upon creation of the new one, ensuring tight control over access without downtime.
- New keys invalidate old ones instantly
- Issue new keys directly from the dashboard
Endpoints Overview
The API exposes three primary endpoints for generating audio and managing resources. The speech endpoint accepts text and voice parameters to return audio files, while the voices endpoint provides metadata on available presets. The models endpoint details the underlying engine options.
Speech Generation Endpoint
Send a POST request to https://api.playgb168.com/v1/audio/speech with a JSON body containing the text, voice, and format. The service processes the input and returns the audio file directly in the response, ready for immediate playback or download.
List Voices Endpoint
Access GET /v1/voices to retrieve the full catalog of eight voice presets, their supported languages, and available audio formats. This endpoint helps you select the right narrator style for your podcast intro or narration without guessing parameters.
- Retrieve voice IDs like 'aria' or 'atlas'
- Check supported languages and formats
- View pricing per voice type
Model Information
Use GET /v1/models to verify the current engine versions. The API supports 'tts-1' and 'tts-1-hd', both using the same underlying engine and pricing structure, ensuring consistent quality across your content generation workflows.
Request Parameters
The API accepts a simple JSON payload where you define the synthesis parameters. You specify the model, select a voice from the eight available presets, and provide the input text to be converted into audio.
Model Selection (tts-1)
Use either "tts-1" or "tts-1-hd" in the model field. Both utilize the same underlying engine and pricing structure, allowing you to choose based on your quality preference without affecting the cost per character.
Voice Selection
Select from eight distinct presets ranging from warm narrators to energetic promo voices. Each voice supports all 23 supported languages, enabling consistent audio style across different content types.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Input Text Limits
Each request supports up to 4,096 characters. For longer scripts, split the text into chunks and join the resulting audio files. Spaces and punctuation count toward this limit.
Response Formats
The API returns audio files in your chosen format, with the default set to MP3. Each response includes the binary audio data, allowing you to save the file directly or play it in your player.
MP3 Output
MP3 is the standard format for most podcast platforms and web players. It offers a good balance between file size and audio quality, making it ideal for distribution where bandwidth matters. Files are generated upon successful synthesis.
WAV Output
WAV provides uncompressed, high-fidelity audio. Use this format if you need raw audio for editing in your DAW or if your publishing pipeline requires lossless input. The resulting files are larger than MP3 but retain full audio detail.
Opus and FLAC
Opus delivers efficient compression suitable for web delivery, while FLAC offers lossless compression for archival quality. Both formats are available via the response_format parameter. Choose Opus for smaller file sizes on mobile networks or FLAC when preserving original fidelity is critical.
Rate Limits
The API enforces a standard rate limit of 60 requests per minute per active key. This cap applies to all synthesis endpoints and ensures stable performance for most podcasting workflows. Since requests are processed sequentially, generating longer texts that require splitting into multiple chunks will consume this quota proportionally.
60 Requests Per Minute
Each account key allows up to 60 API calls per minute. This limit is shared across all requests, including retries and list endpoints. For most content creators generating standard-length episodes, this provides sufficient throughput without requiring complex batching logic.
- Limit applies per API key, not per IP address.
- Shared across all request types for the same key.
Initial Limit
New accounts start with a reduced limit of 10 requests per minute. This lower threshold remains in effect until the first top-up is processed. Once you add USDT via TRC-20, the limit automatically increases to the full 60 requests per minute.
Queue Behavior
Requests are processed one after another. Under heavy load, your synthesis job may wait in a queue before generation begins. Short phrases typically take a few seconds, while longer texts may take longer due to the split-and-join process. Be patient with your requests; the system guarantees eventual delivery.
- Processing is sequential, not parallel.
- Queues form during high-demand periods.

Error Handling
Handling errors in the PodcastVoice API ensures your podcast production pipeline stays smooth. When synthesis fails, charges are fully refunded, so you never pay for broken audio. Understanding common error codes helps you debug quickly without losing credits.
Common Error Codes
Use standard HTTP status codes to identify issues. A 401 error indicates an invalid or expired API key. A 429 error means you have hit the rate limit of 60 requests per minute. Check your dashboard to verify your key and current usage limits.
- 401: Unauthorized (Invalid API Key)
- 429: Too Many Requests (Rate Limit Exceeded)
- 500: Internal Server Error (Temporary service issue)
Retry Logic
Implement exponential backoff for 429 and 500 errors. Wait briefly before retrying to avoid overwhelming the queue. Since requests are processed sequentially, short delays help prevent further throttling. Failed requests are free, so retrying is safe even if the audio generation takes time.
Character Limit Errors
The API rejects input texts exceeding 4,096 characters. Split long scripts into smaller chunks before sending them. Join the resulting audio files on your end. This ensures consistent performance and avoids truncation errors during synthesis.
Code Examples
The API accepts standard JSON payloads, making integration straightforward for podcasters and content creators. You can test the endpoint immediately using cURL, or leverage existing OpenAI SDKs by simply adjusting the base URL.
Below are three practical examples showing how to send text for synthesis in your preferred environment, ensuring you can generate narration or voiceovers quickly.
cURL Example
Use this command to generate speech directly from your terminal. Replace YOUR_API_KEY with your key from the dashboard.
curl -X POST https://api.playgb168.com/v1/audio/speech \-H 'Authorization: Bearer YOUR_API_KEY' \-H 'Content-Type: application/json' \- ` -d '{"model": "tts-1", "input": "Hello world", "voice": "nova"}'`
Python SDK Example
Install the OpenAI package and point it to our base URL. This allows you to use familiar Python code to generate audio files for your podcasts.
import openaiclient = openai.OpenAI(base_url='https://api.playgb168.com/v1', api_key='YOUR_API_KEY')response = client.audio.speech.create(model='tts-1', voice='sage', input='Welcome to my show')
JavaScript Example
For web-based workflows, use the fetch API or the OpenAI JS client. Adjust the base URL to route requests to our TTS service.
const response = await fetch('https://api.playgb168.com/v1/audio/speech', {method: 'POST',headers: { 'Authorization': 'Bearer YOUR_API_KEY' },body: JSON.stringify({ model: 'tts-1', voice: 'aria', input: 'Intro' })});
Language Settings
Our API handles language detection automatically, but explicit control ensures precision for your podcast narration. Understanding how the engine interprets your input text is key to getting natural-sounding audio every time.
You can either let the system guess the language based on the script or explicitly define it using ISO codes. This flexibility supports our 23 supported languages, including English, Spanish, Japanese, and Arabic.
Auto-Detection
The API analyzes the input text to determine the language. It works well for standard scripts, but may require guidance for mixed-language content or ambiguous characters.
This feature simplifies integration, allowing you to generate speech in any of the 23 supported languages without managing complex language parameters for every request.
Explicit Language Code
For reliable results, send the language parameter with an ISO code (e.g., en, es, ja). This overrides auto-detection and ensures the correct voice model is applied.
This is crucial for non-English Latin-script text, where auto-detection might default to English, leading to unnatural pronunciation in your podcast episodes.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
Latin Script Default
If no language is set and the text uses Latin characters, the API defaults to English. This is a common pitfall for creators using non-English text with standard alphabets.
Always set the language parameter for non-English Latin text to avoid unintended English pronunciation in your narration.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Each voice is built from licensed LibriTTS-R recordings, providing a professional foundation for high-quality audio generation.
23 languages
Any voice speaks any of these languages.
