Frequently asked questions
How do I get an API key?
Sign up on /get-api-key/ using Google or an email and password. Your account page displays your active API key, balance, trial status, characters left, usage, and a ready curl example. You can issue a new key at any time, which immediately invalidates the previous one. Each site account is independent.
Is the API compatible with OpenAI SDK?
Yes. The request shape matches the OpenAI speech endpoint exactly. You can use the official OpenAI SDKs by simply changing the base_url to https://api.playpwpw.com/v1 and providing your PlayPW key. This allows immediate integration without rewriting your client code.
What is the base URL?
The API base URL is https://api.playpwpw.com/v1. You will use this endpoint for all requests, including generating speech at /v1/audio/speech, listing voices at /v1/voices, and checking models at /v1/models. Ensure your SDK or HTTP client points to this address.
How do I authenticate requests?
Include your API key in the Authorization header as a Bearer token. The format is: Authorization: Bearer tts-<your-key>. Each account has one active key at a time. If you generate a new key, the old one stops working immediately.
What models are available?
Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing. You can select either model in your API requests. The choice does not affect the cost, which is $10 per 1 million characters for both options.
How do I change the voice?
Specify the voice parameter in your request body. Choose from eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narration to deep documentary styles. You can switch voices per request.
Can I adjust the speed?
Yes, you can set the speed between 0.25 and 4.0. Adjusting speed helps tailor the audio to your product descriptions or notifications. Higher values make speech faster, while lower values slow it down for clarity.
What formats are returned?
You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the response_format field in your request. MP3 is suitable for web playback, while WAV and FLAC offer lossless quality. PCM provides raw audio data for further processing.
What is the rate limit?
You are limited to 60 requests per minute per key. New accounts start with a limit of 10 requests per minute until the first top-up. If you exceed the limit, requests may be delayed or rejected. Monitor your usage on the dashboard.
How do I handle errors?
If synthesis fails, the request is free, and the charge is returned in full. Check your response status codes and error messages for details. Ensure your text is under 4096 characters and your voice ID is valid. Failed requests do not consume credit.
Is there a limit on text length?
Each request supports up to 4096 characters. If your text exceeds this, split it into smaller parts and join the resulting audio files. Spaces and punctuation count toward the character limit. This ensures consistent processing and avoids timeouts for long scripts.
How long does a request take?
Generation is roughly real-time, about 25 characters per second. Short phrases may take a few seconds. Under load, requests are processed sequentially, so you might experience queue delays. Longer texts take longer to generate proportionally to their length.
Can I stream audio?
No, streaming is not supported. The API returns the complete audio file upon request completion. You cannot receive partial audio chunks. For real-time needs, you may need to implement client-side buffering or pre-generate audio files for your product content.
Do I need to install a library?
No, you can use plain HTTP requests or the official OpenAI SDK. No custom library is required. Just point your HTTP client to the base URL and send JSON payloads. This keeps your integration lightweight and flexible for any tech stack.
First request
curl
curl https://api.playpwpw.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.playpwpw.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.playpwpw.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 |
Get Your API Key
Start by visiting the /get-api-key/ page on playpwpw.com to create your account. You can sign up using your Google account for instant access to a free trial, or use an email and password. This step initializes your dashboard where you can manage your integration.
Once registered, navigate to the dashboard to locate your unique API key. This key authenticates your requests to the API base URL. Keep it secure, as it is the only credential needed to generate speech for your product descriptions and notifications.
Sign up on the site
Access the /get-api-key/ page to begin. Choose Google for immediate access with a free trial, or use standard email registration. This creates your account on our independent storefront.
Retrieve key from dashboard
Log in to your account dashboard. Your API key is displayed prominently at the top. Copy this value to include in your Authorization: Bearer header for all API calls.
One key per account
Each account is issued exactly one active API key. This key provides access to your balance and usage history. You can generate a new key at any time from the dashboard; the previous key becomes invalid immediately upon creation.
First Request with cURL
Generate speech by sending a POST request to the API endpoint. This basic example converts a short product description into an audio file, demonstrating the core workflow for e-commerce teams.
Authentication is handled via a Bearer token in the header. Replace the placeholder with your unique key from the dashboard to authorize the request.
Basic speech generation
Send a POST request to https://api.playpwpw.com/v1/audio/speech. The API accepts JSON input and returns audio data (binary or formatted based on response_format) directly in the response body.
Authentication header
Include your API key in the Authorization header using the Bearer scheme. This key is generated during signup and is unique to your account.
JSON body structure
The request body requires the model, input text, and voice preset. Ensure the text does not exceed 4096 characters. You can optionally specify the response format and speed.
- model: "tts-1" or "tts-1-hd"
- input: your product text
- voice: e.g., "aria" or "nova"
OpenAI SDK Integration
PlayPW’s API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing integrations with minimal configuration. By updating the base URL, your code communicates directly with our TTS engine using standard protocols.
Change base URL
Point your client to https://api.playpwpw.com/v1 instead of the default OpenAI endpoint. This single change directs all requests to our infrastructure while maintaining compatibility with standard HTTP clients.
Use official SDKs
You can use the official OpenAI SDKs for Python, Node.js, and other languages. Simply initialize the client with our base URL and your unique API key to start generating speech instantly.
Compatible request shape
The request body follows the same schema as the OpenAI speech endpoint. Send your product copy as input, select a voice, and specify model and response_format exactly as you would for OpenAI.
Request Parameters
Configure speech generation by selecting the model, voice, and speed. The API accepts tts-1 and tts-1-hd as model identifiers, both using the same engine and pricing tier. You can generate audio in eight distinct presets, ranging from warm narrators to deep documentary styles, each capable of speaking any of the 23 supported languages.
Adjust the speaking rate between 0.25 and 4.0 to match your brand’s tone. Faster speeds work well for quick notifications, while slower rates suit detailed product descriptions. The language parameter is optional; if omitted, the system guesses the language from the script, defaulting to English for Latin text.
Model selection (tts-1, tts-1-hd)
Both tts-1 and tts-1-hd use the identical synthesis engine and incur the same charge of $0.01 per 1,000 characters. Choose based on your quality preference; both models use the same engine and pricing.
- - Model parameter accepts:
tts-1ortts-1-hd - - Same engine quality for both options
- - Identical pricing: $10 per 1 million characters
Voice presets
Select from eight licensed voices to match your store’s personality. Options include female voices like Aria and Nova, and male voices like Felix and Milo. Each voice is based on licensed recordings and supports all 23 languages, allowing you to localize content without hiring new voice talent.
Ensure the language parameter matches your target market if using non-English Latin scripts, as the system defaults to English detection. Every generated file includes an inaudible watermark identifying it as synthetic speech.
- - 8 presets: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion
- - Supports 23 languages
- - No voice cloning or custom design
Speed control
Set the speed parameter between 0.25 and 4.0 to control playback rate. This allows you to optimize audio length for mobile data usage or improve comprehension for complex product details. Requests are processed sequentially, so extreme speeds may slightly affect generation time under load.
- - Speed range: 0.25 to 4.0
- - Affects playback rate only
- - No impact on character pricing
Response Formats
PlayPW returns generated audio as binary data in the response body. You can request five formats: MP3, WAV, Opus, FLAC, or PCM. Choose based on your storage needs or playback requirements.
MP3, WAV, Opus, FLAC, PCM
Select the response_format field in your request. MP3 and Opus offer smaller file sizes for web delivery. WAV and FLAC provide uncompressed audio for high-quality archiving. PCM is raw data for custom processing pipelines.
Binary audio data
The API returns the audio file directly as binary content. There is no JSON wrapper around the audio bytes. Save the response body directly to a file on your server or stream it to the user's browser.
Headers and status codes
A successful request returns HTTP 200. The response includes standard HTTP headers. Check the Content-Type header to confirm the audio format you requested. Failed synthesis returns an error code and returns the charge in full.

Rate Limits
PlayPW uses a per-key rate limit to ensure stable generation for e-commerce teams. Understanding these limits helps you plan batch processing for product descriptions or help content without unexpected interruptions.
60 requests per minute
Each API key allows up to 60 requests per minute. This limit applies per key, so you can scale by generating additional keys if needed for higher throughput.
10 requests before top-up
New accounts start with a lower limit of 10 requests per minute. Once you top up your balance, the limit increases to the full 60 requests per minute.
Queue behavior under load
Requests are processed sequentially. Under heavy load, your request may wait in a queue before synthesis begins. Typical speed is roughly real time, but short phrases may take a few seconds.
Error Handling
Errors are straightforward: check your status code and message. Failed synthesis requests are free, with charges returned in full, so you won’t pay for wasted compute. This protects your budget when network hiccups or invalid parameters occur during high-volume product description generation.
Always verify your input text length and voice ID. If a request fails, the API returns an error response detailing the issue, making it easy to adjust your integration logic.
Common error codes
Most errors stem from invalid parameters, such as an unsupported language code or a voice ID that doesn’t exist. A 400 status indicates a bad request, while 401 means your API key is invalid or expired. Check the response body for a specific error message to pinpoint the issue quickly.
- 400 Bad Request: Invalid input or parameters.
- 401 Unauthorized: Missing or invalid API key.
- 429 Too Many Requests: Exceeded rate limits (60 req/min).
Refunds for failures
If synthesis fails, the charge is returned in full. You only pay for successful audio generation. This ensures you aren’t billed for empty responses or processing errors, keeping your cost-per-character accurate even during occasional hiccups.
Debugging requests
Enable logging in your SDK to capture the full request payload and response headers. If you encounter persistent errors, verify your text is under 4096 characters and your key is active. Contact support via email with your request ID for further assistance.
Voice and Model Details
Explore the eight voice presets designed for e-commerce contexts, from warm narrators to energetic promo voices. Each voice supports all 23 languages, allowing you to generate consistent audio for product descriptions and help content globally.
List available voices
Our eight presets cover diverse tones, including warm narrators for storytelling and neutral voices for news-style updates. All voices support any of the 23 listed languages, ensuring consistent brand audio across international stores.
- 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)
Check model endpoints
Use the GET /v1/models endpoint to verify available configurations. Both tts-1 and tts-1-hd use the same engine and pricing, giving you flexibility without complexity.
Language support
Supports 23 languages, including English, Spanish, German, French, Japanese, and Arabic. Any voice can speak any language in this list. If you omit the language field, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin scripts, always set the language parameter explicitly.
- Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Streamline your digital storefronts to boost conversion rates and delight every shopper with seamless experiences across all devices.
23 languages
Any voice speaks any of these languages.
