Frequently asked questions
Do I need to hire a developer?
Not necessarily. Our API follows the OpenAI request shape, so standard HTTP libraries or even tools like Postman can generate audio. If you prefer a code-free approach, you can use our ready curl examples or connect via simple automation tools without hiring a dedicated engineer.
Can I integrate without coding?
Yes. Since the endpoint accepts standard JSON, you can use no-code automation tools to send text and receive audio files. You can also use our /get-api-key/ page to generate audio directly for testing or small batches without writing any code.
How long does integration take?
Integration is typically quick because the API mimics the OpenAI speech endpoint. You only need to update the base URL and pass your Bearer token. Basic integration takes minutes, while complex workflows with long text splitting may take a few hours.
Is the API easy to use?
Yes. It uses a simple POST request with fields like model, input, and voice. The official OpenAI SDKs work by just changing the base_url. You get an MP3, WAV, or other format back immediately, making it straightforward for any developer.
Do I need a backend server?
No. You can call the API directly from your frontend if you manage your API key securely. However, using a backend server is recommended to hide your key and handle rate limits or retries more gracefully without exposing credentials to users.
Can I cache the audio files?
Yes. Since audio files are static once generated, you can store them in your own CDN or storage. We do not store the generated audio, so caching it yourself is the best way to reduce repeated API calls and costs.
How do I handle long product descriptions?
Split the text into parts of up to 4096 characters. Generate audio for each part and join the files. Our API handles one request at a time, so splitting ensures you stay within character limits and manage queue times effectively.
What if the API is down?
We do not provide an SLA or uptime guarantee. If synthesis fails, the charge is returned in full. You should implement retry logic in your application to handle temporary failures gracefully without losing your credit balance.
Can I update the text later?
Yes. Since we do not store the generated audio, you can regenerate the audio anytime by sending the updated text. You just need to make a new API call with the new input and receive a fresh audio file.
Do I need to pay for each request?
You pay based on character count: $10 per 1 million characters. Failed requests are free. You top up with USTRC-20, and the balance does not expire. You only pay for successful synthesis, making it cost-effective for variable traffic.
Is the audio stored on your servers?
No. Generated audio is returned in the response and not stored by us. Input text is used only to produce the audio and is not used for training. We keep request metadata for billing purposes only.
Can I change the voice later?
Yes. You can switch between any of the 8 voices (e.g., aria, nova, felix) by changing the voice parameter in your next API request. There is no lock-in, allowing you to test different tones for your products.
What happens if I exceed limits?
You are limited to 60 requests per minute per key. If you exceed this, requests may queue or fail. You can monitor your usage on the dashboard and upgrade your key or wait for the rate limit window to reset.
Do you provide example code?
Yes. The /get-api-key/ page displays a ready curl example. You can also use the official OpenAI SDKs by setting the base_url to our API endpoint. This makes integration quick for developers familiar with standard HTTP clients.
Step 1: Get Your API Key
To start generating speech for your product descriptions, you need an API key. Visit the /get-api-key/ page on playpwpw.com to create an account. You can sign up using Google for immediate access or use a standard email and password combination. This account is specific to this storefront and tracks your usage separately.
Sign up for an account
Registration takes only a few seconds. If you use Google, you immediately receive $0.50 in trial credit, valid for 7 days, which covers about 50,000 characters. Accounts created with email and password start without this trial credit but are ready for top-up via USDT (TRC-20).
- Support Google or Email/Password authentication
Access the dashboard
Once logged in, you land on your dashboard. This central hub displays your current balance, characters remaining, and usage history. It also shows your active API key and provides a ready-to-use cURL example, so you can start testing immediately without guessing the request structure.
Copy your secret key
Locate your unique key in the dashboard. It begins with 'tts-'. Copy this key carefully, as it authenticates all your requests. You can issue a new key at any time, which instantly invalidates the old one, ensuring your credentials remain secure if exposed.
- Key format: tts-...
Step 2: Prepare Your Text
Before sending data to the API, ensure your product descriptions are clean and ready for synthesis. Extract only the essential text from your store’s backend, avoiding HTML tags or metadata that won’t translate to audio.
Keep an eye on length limits. The API accepts up to 4,096 characters per request. Anything longer must be split logically to ensure coherent audio output without truncation.
Extract product descriptions
Pull the raw text from your e-commerce platform’s database. Focus on concise, natural-sounding sentences that describe features and benefits clearly.
Remove special characters, bullet points, and formatting codes that don’t convey meaning when spoken aloud.
- Use plain text only
- Remove HTML tags
- Keep sentences concise
Split long texts
If your description exceeds 4,096 characters, divide it into smaller chunks. Each chunk becomes a separate API request.
Join the resulting audio files sequentially to maintain narrative flow for the listener.
This approach ensures consistent quality and avoids hitting character limits mid-sentence.
- Max 4,096 chars per request
- Split at sentence boundaries
- Join audio files afterward
Format for API
Ensure the text is UTF-8 encoded and free of control characters. Specify the language ISO code if it’s not English to avoid guessing errors.
Set the response_format to your preferred audio type (mp3, wav, opus, flac, or pcm), depending on your store’s playback capabilities.
Keep the text free of markdown or bolding syntax, as these won’t affect speech synthesis but add unnecessary characters.
- UTF-8 encoding
- Set language ISO code
- Choose response format
Step 3: Make the API Request
Send your product copy to the speech endpoint using a simple POST request. You can use standard tools like cURL or the official OpenAI SDK by adjusting the base URL. This ensures compatibility with existing codebases while keeping the integration lightweight for your engineering team.
Use cURL or OpenAI SDK
The API accepts standard JSON bodies, making it easy to integrate with your backend. Use the OpenAI SDK for structured code or cURL for quick testing. Both methods support the same request parameters, allowing flexible implementation depending on your stack.
- Supports both raw HTTP requests and SDK wrappers
- Accepts text up to 4096 characters per call
- Returns audio in formats like MP3, WAV, or OPUS
Set base URL correctly
Point your requests to https://api.playpwpw.com/v1 to ensure they reach the correct service. Using the wrong endpoint will result in errors, so double-check your configuration before sending product descriptions. This base URL works seamlessly with OpenAI SDK configurations.
Include authentication header
Every request must include your secret key in the Authorization: Bearer <key> header. You can find this key in your dashboard after signing up. Keep this key secure in your backend environment variables to prevent unauthorized usage of your character balance.
Step 4: Handle the Response
The API response delivers the generated audio file directly in the body, in the format you requested (mp3, wav, opus, flac, or pcm). This binary data must be captured immediately upon receiving the HTTP 200 status code to ensure the audio stream remains intact.
Receive audio file
Upon a successful request, the response body contains the raw audio bytes. Ensure your code parses this binary data correctly without attempting to interpret it as JSON. The format matches your response_format parameter, allowing immediate playback or processing.
- Check for HTTP 200 status before parsing
- Verify the
Content-Typeheader matches your request - Handle binary data, not JSON strings
Save to storage
Store the received audio file in your cloud storage (e.g., S3, Blob Storage) or local server directory if you choose to cache it. Each file should be named with a unique identifier linked to the specific product or notification to prevent overwriting.
- Use unique filenames tied to the product ID
- Compress storage if using limited local disk space
- Maintain a mapping between audio files and store items
Return URL to frontend
Once saved, generate a public URL or a signed temporary link for the audio file. Return this URL in your API response to the frontend so the audio player can reference the correct file without re-downloading from the TTS API, if you have stored it.
- Generate signed URLs for secure access
- Cache the audio URL in your product database
- Ensure the URL is accessible to end-users
Step 5: Display Audio on Store
Once the API returns the audio file, store it in your cloud storage and save the public URL. This allows your frontend to reference the audio without re-generating it on every page view, keeping your initial load times fast and reducing API calls.
Present the audio clearly to shoppers by embedding a standard HTML5 player. This ensures broad compatibility across all modern browsers and devices.
Subsections and image omitted for brevity in this thought trace, but will be generated in the final JSON output.
Embed audio player
Use the native HTML5 <audio> tag to embed the player. Pass the stored URL from your storage to the src attribute. This approach is lightweight, accessible, and requires no additional dependencies.
Ensure the player controls are visible and intuitive. Users should be able to pause, seek, and adjust volume easily. This improves the shopping experience for users who prefer listening to reading product details.
- Use <audio src='...'> for simple integration
- Ensure controls are visible and accessible
- Avoid heavy custom JavaScript players
Add play button
Place a prominent play button next to the product description. This invites users to listen without disrupting the visual layout. A clear call-to-action encourages engagement with the audio content.
Consider adding a short label like 'Listen to product details' above the button. This sets user expectations and clarifies the value of the audio, especially for those scanning quickly.
- Place button near product description
- Add clear label like 'Listen'
- Ensure button is clickable on all devices
Ensure mobile compatibility
Test the audio player on various mobile devices and browsers. Ensure the player scales correctly and touch events work smoothly. Mobile users should have the same experience as desktop users.
Avoid autoplay on mobile if it consumes data unexpectedly. Let users choose when to play the audio. This respects their data plans and improves overall satisfaction with the store.
- Test on iOS and Android
- Ensure touch events work
- Avoid aggressive autoplay
Step 6: Manage Costs
Keep your store running smoothly by tracking character consumption in real-time. The dashboard displays your current balance, remaining trial credit, and usage history, so you always know exactly how much you’ve spent and how many characters are left.
Monitor usage
The dashboard shows your current balance, remaining trial credit, and usage history. This transparency helps you predict costs before they exceed your budget.
Top up balance
Add funds via USDT on the TRON network (TRC-20). Minimum top-up is $5, and credits are available within minutes. No subscriptions or invoices.
- USDT (TRC-20) only
- Minimum $5 top-up
- Credits available in minutes
Optimize character count
Prices are $0.01 per 1,000 characters, including spaces. Shorten product descriptions or use the free trial credit ($0.50) for initial testing to minimize waste.
- $0.01 per 1,000 characters
- Spaces count as characters
- Failed requests are free
Step 7: Handle Errors
Errors are a normal part of integration, especially when dealing with network latency or high traffic. Understanding how the API handles failures ensures your store remains reliable without unnecessary customer friction. Most issues are transient and resolvable with simple adjustments to your integration logic.
The API distinguishes between billing failures (e.g., insufficient funds) and temporary processing delays. Knowing the difference helps you decide whether to retry immediately or wait before attempting again, keeping your costs accurate and your user experience smooth.
Check rate limits
Each API key allows 60 requests per minute, dropping to 10 per minute before the first top-up. Exceeding this limit returns a 429 error. Monitor your request frequency to avoid throttling, especially during flash sales or heavy traffic periods.
If you hit the limit, wait briefly before resuming. The limit resets automatically every minute, so you don’t need to restart your service or wait for a new key.
- Limit is 60 requests/minute per key
- Starts at 10 requests/minute until first top-up
- Returns 429 status code when exceeded
Retry failed requests
Failed synthesis requests are free, so retrying is safe. If a request fails due to a transient issue, retry it once or twice with exponential backoff. Do not retry indefinitely, as the queue may still be processing.
- Failed requests are free
- Use exponential backoff for retries
- Avoid infinite retry loops
Log errors for debugging
Log error codes, timestamps, and input text to diagnose issues quickly. This helps identify patterns, such as consistent failures for specific voices or formats. Detailed logs are essential for troubleshooting without relying on support.
- Log error codes and timestamps
- Include input text for context
- Share logs via email support

Step 8: Optimize Performance
Optimizing performance ensures your store remains snappy while delivering rich audio content. By caching and pre-generating audio, you reduce latency and keep your API usage predictable.
These strategies help you avoid rate limits and provide a seamless experience for shoppers browsing product descriptions or help content.
Cache generated audio
Store generated audio files in your CDN or object storage. Since input text is not stored by the API, you must handle persistence locally.
Use cache keys based on the text hash, voice, and speed. This prevents redundant API calls for identical product descriptions.
- Cache keys should include voice and speed settings.
- Invalidate cache when product copy changes.
Pre-generate popular items
Identify your top-selling products or frequently viewed help articles. Generate their audio versions during off-peak hours or via a background job.
This ensures instant playback for high-traffic items without waiting for real-time synthesis, which can take seconds for short phrases.
Use async processing
Don’t block the user’s browser while generating audio. Trigger synthesis via a background worker and notify the frontend when ready.
This is especially useful for long product descriptions that approach the 4096-character limit, requiring multiple requests to join audio files.
Step 9: Test Integration
Testing ensures your store’s audio features work correctly before going live. Verify that the API key, base URL, and request body match your integration settings. Use short and long sample texts to confirm character limits and language detection.
Check that the generated audio plays correctly on both desktop and mobile devices. Ensure the audio file format matches your frontend player’s requirements.
Test with sample texts
Send requests with varying text lengths, including edge cases like special characters and non-Latin scripts. Confirm that the API returns valid audio files and that the character count matches your billing expectations.
- Use texts up to 4096 characters.
- Include special characters and punctuation.
- Test different languages supported by the API.
Verify voice selection
Confirm that each voice preset (e.g., aria, nova, felix) produces the expected tone and style. Ensure the voice parameter in your request matches the desired output.
- Test each of the 8 voice presets.
- Verify tone matches product content (e.g., calm for instructions, upbeat for promos).
- Confirm voice selection persists across multiple requests.
Check audio quality
Listen for clarity, natural speech flow, and any artifacts. Ensure the audio is playable in your store’s player and that the inaudible watermark is present (though not audible).
- Check for clear speech and no artifacts.
- Ensure audio plays in all supported formats (mp3, wav, etc.).
- Verify watermark presence if required for compliance.
Step 10: Go Live
Deploy your integration to the live environment once testing confirms the audio generation pipeline works correctly. Ensure your backend routes the POST requests to https://api.playpwpw.com/v1/audio/speech with the correct base URL and authentication header.
Monitor the initial production requests closely. Check that the API key remains active and that rate limits (60 requests per minute) are not exceeded during traffic spikes. Verify that audio files are returned successfully and stored appropriately.
Deploy to production
Push the updated store code to your live server. Confirm that the API endpoint is reachable and that your secret key is correctly injected from your environment variables. Ensure the response format matches your frontend player requirements.
- Verify base URL: https://api.playpwpw.com/v1
- Check authentication header format
- Confirm environment variable injection
Monitor first requests
Watch the dashboard for the first few synthesis jobs. Since requests are processed sequentially, you may notice slight delays if multiple users trigger audio generation simultaneously. Ensure the status codes indicate success and that billing charges appear correctly.
- Check response status codes
- Verify billing charges
- Monitor queue wait times
Gather user feedback
Ask early users if the audio quality meets their expectations. Note any issues with voice selection or language detection. Use this feedback to adjust speed settings or switch voices for specific product categories.
Common Pitfalls
Integration issues often stem from simple configuration errors rather than complex code bugs. Ensuring your requests hit the correct endpoint and include valid credentials prevents most common failures.
Below are the specific pitfalls to avoid when connecting PlayPW to your store’s backend or frontend.
Incorrect base URL ['The API base URL is https://api.playpwpw.com/v1, not the standard OpenAI endpoint. Using the wrong URL will result in connection errors or unexpected responses.', 'Even if you use the OpenAI SDK, you must explicitly set the base_url parameter to point to the PlayPW API domain.'] ['Verify base_url is set to https://api.playpwpw.com/v1', 'Ensure the path includes /v1/audio/speech']
Missing authentication ['Every request must include the Authorization: Bearer tts-... header. Without it, the API will reject the request with a 401 error.', 'Ensure you are using the active key from your dashboard. If you issue a new key, the old one stops immediately, which can break active integrations.'] ['Include Authorization: Bearer <your-key> in every request', 'Check that the key is active and matches your account']
Exceeding rate limits ['The API allows 60 requests per minute per key. If you exceed this, requests may be delayed or rejected.', 'New accounts start with a limit of 10 requests per minute. Ensure your integration respects these limits to avoid service interruptions.'] ['Monitor request frequency to stay under 60 RPM', 'Implement retry logic with exponential backoff for transient errors']
Support and Resources
Support is available by email only. We do not offer live chat, phone numbers, or guaranteed response times. For urgent issues, please include your API key and request ID in your message so our team can locate your account quickly.
The API documentation provides reference guides for all endpoints, including voice lists, pricing, and rate limits. You can find ready-to-use code examples for cURL and the OpenAI SDK to help you get started with the integration.
Email support
We respond to support emails as soon as possible. Since we do not have a phone number or live chat, email is our primary channel for technical questions and billing inquiries. Please be specific about the endpoint and error message you encountered.
API documentation
Our documentation covers the full specification for the TTS API. It includes details on request parameters, response formats, and error codes. You can also find example curl commands to simplify the integration process for your e-commerce platform.
- Full endpoint reference
- Authentication guide
- Code examples
Community forums
While we do not host official forums, developers often share integration tips and custom scripts in public tech communities. You can search for PlayPW discussions or post questions using the #tts-ecommerce tag to find peer support and troubleshooting advice from other product teams.
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.
Sources and further reading
- Wikipedia
- W3C WAI: making audio and video accessible
- openai-python on GitHub
- IETF RFC 7845: Ogg Opus
- LibriVox public-domain audiobooks
- TRON developer hub: TRC-20
- MDN: Web Speech API
- Creative Commons Attribution 4.0
- Python documentation
- FFmpeg documentation
- LibriTTS-R paper (arXiv 2305.18802)
- LibriTTS-R corpus (OpenSLR 141)
