Comprehensive Guide to Integrating the ShopVoice Text-to-Speech API

By ShopVoice editorial team · Updated 2026-11-18

This guide helps no-code store owners integrate natural-sounding speech into their online shops. You will learn how to generate audio from text using simple code or your store’s backend. The instructions cover everything from getting your API key to making your first request with curl or the OpenAI SDK.

We explain the supported formats, voices, and rate limits so you can build reliable product pages and ads. You can test the service with a free trial, then scale up with USDT top-ups. The API works exactly like the OpenAI speech endpoint, so you can reuse familiar tools without building a custom client.

Comprehensive Guide to Integrating the ShopVoice Text-to-Speech API

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

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

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

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

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

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

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

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

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

Rate limits and errors

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

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

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

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. Python documentation
  3. IETF RFC 7845: Ogg Opus
  4. Node.js documentation
  5. MDN: Web Speech API
  6. OpenAI API reference: create speech
  7. ISO 639 language codes
  8. TRON developer hub: TRC-20
  9. openai-python on GitHub
  10. curl documentation
  11. LibriVox public-domain audiobooks
  12. Creative Commons Attribution 4.0

More on this site