Frequently asked questions
How do I generate an API key?
Sign up on the /get-api-key/ page using Google or an email and password. Your account is specific to this site. The dashboard displays your active API key, current balance, and usage statistics.
Can I use the OpenAI SDK with this API?
Yes. The API uses the same request shape as the OpenAI speech endpoint. You can use the official OpenAI SDK by changing the base_url to https://api.playg9999.com/v1 and providing your ShopVoice API key.
What is the character limit per request?
Each request supports up to 4096 characters in the input field. For longer texts, split your content into parts of this size and join the resulting audio files. Spaces and punctuation count toward the limit.
Does the API support SSML?
No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You can adjust the speed parameter between 0.25 and 4.0, but there are no emotion tags or SSML markup options available.
How do I handle rate limits?
You are limited to 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so under load, a request may wait in a queue. Monitor your usage on the dashboard.
Can I change my API key if it leaks?
Yes. You can issue a new API key at any time from your account dashboard. The old key stops working immediately when the new one is generated, ensuring your previous key cannot be used.
What audio formats are available?
You can specify mp3, wav, opus, flac, or pcm using the response_format field. The API returns the audio file directly in the response based on your selected format preference.
Is the response JSON or binary?
The response contains the audio file directly. You send text via a JSON body to the POST endpoint and receive the generated audio data. Failed requests return an error status but are free.
Do I need to pay for every request?
You pay $0.01 per 1,000 characters. Failed requests are free, and the charge is returned in full if synthesis fails. You can start with a $0.50 free trial valid for 7 days when signing in with Google.
How do I specify the language?
Use the optional language field with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting it ensures correct pronunciation for non-English languages.
Can I use custom voices?
No. The API offers eight fixed presets (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion). There is no custom voice cloning, voice uploading, or voice design feature available for customers.
Is there a SDK for mobile apps?
No. There is no mobile SDK. You can use the standard OpenAI SDK or plain HTTP requests by pointing the base URL to https://api.playg9999.com/v1 from your mobile application.
How do I split long texts?
Split your text into chunks of up to 4096 characters. Send each chunk as a separate request and then join the resulting audio files. This ensures you stay within the per-request character limit.
What happens if the server is down?
There is no SLA or uptime guarantee. Requests are processed sequentially, so delays may occur under load. Failed requests are free, and you can retry them. Support is available via email only.
First request
curl
curl https://api.playg9999.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.playg9999.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.playg9999.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
To start generating speech, visit the /get-api-key/ dashboard. You can create an account using Google for an instant $0.50 free trial, or use your email. This credit covers about 50,000 characters and lasts 7 days, letting you test voices before paying.
Sign up on the dashboard
Visit the signup page to create your account. You can sign up with Google or an email and password. If you use Google, you receive a $0.50 trial credit immediately. Email-based accounts start without trial credit.
Generate a new key anytime
Your dashboard displays your active API key and current balance. You can issue a new key at any time. This is useful if you suspect your key has been exposed.
One active key per account
Each account holds only one active key. When you generate a new key, the old one stops working immediately. Ensure you update your store’s backend configuration promptly after rotation.
First request with curl
Once you have your API key from the dashboard, you can start generating speech immediately. The ShopVoice API follows the standard OpenAI request shape, making it easy to test with simple command-line tools or your existing codebase without learning a new protocol.
This curl example demonstrates a basic synthesis request. Replace YOUR_API_KEY with your actual key and adjust the text, voice, and format parameters to match your specific e-commerce use case, such as a product description or promotional update.
Set the Authorization header
Authentication is handled via a simple Bearer token. Include your key in the HTTP Authorization header to prove your identity and allow the API to bill your account correctly. Ensure the key starts with 'tts-' and contains no extra spaces.
- Format: Authorization: Bearer YOUR_API_KEY
- Key format: tts-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- One active key per account; replace old keys instantly
Send POST request to /v1/audio/speech
Send a POST request to the speech endpoint with a JSON body containing the text, voice, and format details. The input text must be under 4,096 characters. For longer product descriptions, split the text into chunks and join the resulting audio files.
The request includes the model (tts-1 or tts-1-hd), the voice preset (e.g., 'nova' for upbeat promos), and the desired response format. Speed can be adjusted between 0.25 and 4.0 to fit your video or audio timeline needs.
- Endpoint: https://api.playg9999.com/v1/audio/speech
- Method: POST
- Max input length: 4,096 characters
- Supported formats: mp3, wav, opus, flac, pcm
Receive audio file in response
Upon successful synthesis, the API returns the audio file directly in the response body. The content type matches your requested format, such as audio/mpeg for MP3. You can save this file directly to your store’s media library or play it in your frontend player.
If the request fails, the API returns an error code and message. Failed requests do not incur charges, and any pre-deducted balance is returned. Check the response status code to handle errors gracefully in your integration.
- Response type: audio file (binary)
- Status 200: Success
- Status 429: Rate limit exceeded
- Status 500: Server error (free retry)
Using the OpenAI SDK
The OpenAI SDKs work with ShopVoice API out of the box. You only need to change the base_url to https://api.playg9999.com/v1 and provide your API key. This allows you to use the standard audio/speech endpoint without building a custom client.
Pass your text, voice, and format preferences just like you would for OpenAI. The SDK handles the JSON body and authentication header automatically. This simplifies integration for no-code developers who already know standard HTTP patterns.
Change base_url to our API
Update your SDK configuration to point to https://api.playg9999.com/v1. This ensures all requests route through our infrastructure while keeping the familiar SDK structure.
- Base URL:
https://api.playg9999.com/v1 - Authentication:
Authorization: Bearer <your-key>
Use standard speech endpoint
Call the standard POST /audio/speech endpoint. Send your text, selected voice, and desired audio format in the JSON body. The API returns the audio file directly.
No custom client needed
You do not need a proprietary client library. The official OpenAI SDKs handle the request shaping. Just ensure your request matches the standard fields: model, input, voice, and response_format.
Supported audio formats
Choose the response_format that best fits your store’s technical needs. MP3 offers universal web compatibility, while WAV ensures high-quality audio for download pages.
MP3 for web compatibility
MP3 is the default choice for embedding audio directly into product descriptions or ads. It balances file size and quality, ensuring fast load times for visitors on any device.
WAV for high quality
Select WAV when you need uncompressed audio for high-fidelity playback or archival purposes. This format is ideal for downloadable audio content or professional presentations.
OPUS, FLAC, PCM options
OPUS provides efficient compression, while FLAC offers lossless quality without compression artifacts. PCM delivers raw, uncompressed audio data for specialized processing pipelines.
- OPUS: efficient streaming
- FLAC: lossless quality
- PCM: raw data
Request parameters
Define how the API processes your text by selecting the appropriate model, input length, and voice style. These parameters determine the audio quality, character limits, and tonal character of the generated speech.
Model: tts-1 or tts-1-hd
Choose between "tts-1" and "tts-1-hd". Both models use the same engine and pricing structure.
Input: text up to 4096 chars
Send up to 4,096 characters per request. Spaces and punctuation count toward this limit. For longer product descriptions, split the text into chunks and join the resulting audio files.
- Maximum: 4096 characters
- Spatial/punctuation counted
Voice: 8 presets available
Select from eight distinct voice presets to match your brand tone. Voices include female options like Aria and Nova, and male options like Felix and Milo.
- Aria, Nova, Luna, Sage
- Felix, Milo, Atlas, Orion

Rate limits and errors
ShopVoice API enforces a standard rate limit of 60 requests per minute per key. This allows steady processing for typical e-commerce workflows, such as generating voiceovers for multiple product descriptions or updating promotional banners without interruption.
60 requests per minute
The limit applies to the active API key. If you exceed this threshold, subsequent requests will be rejected until the window resets. For most small to medium stores, this capacity handles routine content generation easily.
10 requests before first top-up
New accounts start with a restricted limit of 10 requests per minute before the first top-up. This ensures fair usage during the free trial period. Once you add USDT (TRC-20) to your balance, the standard 60 requests per minute limit applies immediately.
- Starts at 10 requests/minute for new accounts
- Increases to 60 requests/minute after first top-up
- Limits reset every minute
Handle 429 and 500 errors
A 429 status code indicates you have exceeded the rate limit. Implement exponential backoff in your integration to retry after a short delay. A 500 error suggests a server-side issue during synthesis; failed requests are free, so you can safely retry or check the /v1/audio/speech endpoint status.
Always check the response body for specific error messages. If synthesis fails, the character count is not deducted from your balance, ensuring you do not pay for incomplete audio files.
- 429: Rate limit exceeded, retry with backoff
- 500: Server error, retry or check logs
- Failed requests are free
Voices endpoint
Use the /v1/voices endpoint to retrieve the full list of available voices, their supported languages, and audio formats. This endpoint provides the metadata you need to configure your text-to-speech requests correctly before sending any audio generation tasks.
GET /v1/voices for list
Send a GET request to this endpoint to receive a JSON array of all eight voice presets. Each entry includes the voice ID (e.g., aria, nova, atlas) and its associated metadata, allowing your application to dynamically populate voice selection menus for your e-commerce store.
- Returns voice ID, name, gender, and associated metadata
- Useful for building dynamic UI components in your store backend
Check language support
Every voice supports all 23 listed languages, including English, Spanish, French, German, Japanese, and Arabic. The API guesses the language from the script if not specified, but you should explicitly set the language parameter for non-English Latin text to ensure accurate pronunciation.
- Full support for 23 languages across all voices
- Explicit language setting recommended for Latin-script non-English texts
- No support for Vietnamese, Indonesian, Thai, or Ukrainian
View available formats
The endpoint also lists supported audio formats: mp3, wav, opus, flac, and pcm. You can choose the format that best fits your store’s technical requirements, such as using MP3 for general web compatibility or WAV for high-quality product demos.
- Supports mp3, wav, opus, flac, and pcm
- Choose based on your store’s audio player capabilities
- Formats do not affect voice quality, only file size and compatibility
Models endpoint
The models endpoint provides a simple list of available synthesis engines. Use this endpoint to verify which models are active for your account.
It returns metadata about the current engine versions, helping you ensure your integration uses the latest stable release.
GET /v1/models
Send a GET request to /v1/models to retrieve a list of available text-to-speech models. The response includes model IDs and basic metadata.
This endpoint helps you confirm which models are currently supported.
- Returns a JSON array of available models
Engine details
Each model entry includes its ID (e.g., 'tts-1' or 'tts-1-hd'). Both models use the same engine.
The engine handles all voice rendering, so you don’t need to manage server-side processing.
- Standard and HD models share the same engine
Pricing per model
Both 'tts-1' and 'tts-1-hd' are priced identically at $10 per 1 million characters. Choose based on voice preference, not cost.
Both models are priced identically, making it easy to upgrade your store’s audio without changing your billing expectations.
- tts-1: $0.01 per 1,000 characters
- tts-1-hd: $0.01 per 1,000 characters
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This voice is ideal for blog posts, FAQ sections, or customer updates where a warm, approachable tone builds trust with your shoppers.
23 languages
Any voice speaks any of these languages.
