Text-to-Speech API Documentation for E-commerce Teams

By PlayPW editorial team · Updated 2026-11-18

This guide helps e-commerce product teams generate natural-sounding audio for store copy, notifications, and help content without building infrastructure. You’ll find everything needed to integrate our simple text-to-speech API into your workflow, from initial setup to handling responses.

We provide concrete examples using cURL and the OpenAI SDK, which works seamlessly by changing the base URL. Learn how to select voices, manage rate limits, and interpret errors. The documentation is specific to online stores, focusing on real workflows and clear, actionable details for your team.

Text-to-Speech API Documentation for E-commerce Teams

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.mp3

Python (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
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

Get Your API Key

Sound wave illustration for: 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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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-1 or tts-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

Sound wave illustration for: 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.

Response Formats

Rate Limits

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

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. Creative Commons Attribution 4.0
  3. FFmpeg documentation
  4. Python documentation
  5. LibriTTS-R corpus (OpenSLR 141)
  6. IETF RFC 7845: Ogg Opus
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. TRON developer hub: TRC-20
  9. MDN: Web Speech API
  10. LibriVox public-domain audiobooks
  11. curl documentation
  12. Node.js documentation

More on this site