Frequently asked questions
What is the API endpoint URL?
Send your POST requests to https://api.playhs55.com/v1/audio/speech. This endpoint accepts a JSON body containing your text, voice selection, and format preferences. It follows the same request shape as the OpenAI speech endpoint.
How do I authenticate?
Include your API key in the Authorization header using the Bearer scheme: Authorization: Bearer tts-... You receive one active key per account. If you need a fresh key, you can issue a new one at any time, and the old key stops working immediately.
What is the character limit per request?
Each request supports up to 4096 characters in the input field. If your text exceeds this limit, you must split it into smaller parts yourself. Send each part as a separate request and join the resulting audio files to create the final output.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work perfectly. You just need to change the base_url to https://api.playhs55.com/v1 and use your site’s key. This allows you to leverage existing SDK functionality.
What audio formats are supported?
You can choose from mp3, wav, opus, flac, and pcm via the response_format field. These options cover most standard use cases, from web playback to high-quality archival. Select the format that fits your delivery pipeline or playback environment requirements.
How do I handle rate limits?
The limit is 60 requests per minute per key. Before your first top-up, this drops to 10 requests per minute. Monitor your usage to avoid throttling. If you exceed the limit, requests may queue or fail, so implement retry logic with exponential backoff.
What happens if the API fails?
If synthesis fails, the charge is returned in full. You are not billed for failed requests. This ensures you only pay for successful audio generation. Check the response status to determine if the request succeeded or if you should retry or adjust parameters.
Do I need to split long texts manually?
Yes, you must split texts longer than 4096 characters. Split them into parts, send each as a separate request, and join the resulting audio files. The API does not handle automatic splitting or joining, so your application logic must manage this process.
Is there a webhook for status updates?
No, there is no webhook support. The API is synchronous; you receive the audio file directly in the response. For long texts, you handle splitting and joining in your own code. There is no background processing queue with notification callbacks.
Can I stream the audio response?
No, streaming is not supported. The API returns the complete audio file in the response body. You cannot receive partial audio chunks. Each request processes sequentially, so you wait for the full file before receiving it.
Do you support SSML?
No, SSML is not supported. You send plain text in the input field. There are no phoneme dictionaries or custom pronunciation lexicons available. Voice control is limited to the selected preset voice and speed adjustments between 0.25 and 4.0.
What is the base URL for the SDK?
Set the base URL to https://api.playhs55.com/v1 when initializing your SDK client. This points the SDK to the correct API endpoints. Ensure you use your specific API key for authentication to access the speech synthesis services provided by this storefront.
How do I rotate my API key?
You can issue a new key at any time from your account page. When you generate a new key, the old one stops working immediately. This ensures only one active key exists per account, simplifying security and access management for your applications.
What are the common error codes?
The API uses standard HTTP status codes. Common errors include 401 for authentication issues, 429 for rate limit exceeded, and 500 for server errors. Failed synthesis requests return a full refund. Check the response body for specific details on what went wrong.
First request
curl
curl https://api.playhs55.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.playhs55.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.playhs55.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 |
Authentication
Secure your API key and include it in every request header. The key is tied to your ReelVoic account and controls access to voice generation endpoints.
API Key Usage
Send your API key with every request using the standard Authorization header. Use one active key per account; you can generate a new one at any time from your dashboard.
Bearer Token Format
Include the header Authorization: Bearer tts-... in your requests. Ensure no extra whitespace or quotes are added to the token string.
Key Rotation
Generate a new key from your dashboard whenever needed. The old key stops working immediately upon issuance of the new one, ensuring clean access control.
Endpoints Overview
The API exposes three primary endpoints for generating audio and retrieving metadata. Each endpoint serves a distinct purpose in the workflow, from creating speech files to listing available voices and models.
All endpoints require authentication via a Bearer token in the Authorization header. Requests are processed synchronously, returning results or errors directly in the HTTP response.
Speech Generation Endpoint
The core endpoint accepts text and returns an audio file. Send a POST request to /v1/audio/speech with your text, voice selection, and desired format. The API processes the request and returns the audio data directly in the response body.
- Endpoint:
POST /v1/audio/speech - Accepts JSON body with
input,voice, andmodelfields - Returns audio file in specified format (mp3, wav, opus, flac, pcm)
Voices List Endpoint
Retrieve the full list of available voices, their associated languages, and supported formats. This endpoint helps you verify which voices are active and which languages they support before generating speech. It provides essential metadata for integration.
- Endpoint:
GET /v1/voices - Returns voice IDs, names, and supported languages
- Includes format and price information for each voice
Models Endpoint
List the available TTS models, including tts-1 and tts-1-hd. Both models use the same engine and pricing. Use this endpoint to confirm model availability and details before making synthesis requests.
- Endpoint:
GET /v1/models - Returns model IDs and descriptions
- Confirms
tts-1andtts-1-hdavailability
Request Parameters
Configure your synthesis requests by selecting a model, defining the input text constraints, and choosing the appropriate voice and language settings to match your content needs.
Model Selection
Choose between tts-1 for standard quality or tts-1-hd for higher fidelity. Both models use the same engine and incur identical pricing, so select based on your audio quality requirements without worrying about cost differences.
Input Text Limits
The input field accepts up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer scripts, split the text into parts and join the resulting audio files to maintain consistent quality.
Voice and Language Options
Select one of eight preset voices, such as aria or atlas. You can optionally specify a language using its ISO code (e.g., en, de). If omitted, the system guesses the language from the script, defaulting to English for Latin text.
- 8 voices available: aria, nova, luna, sage, felix, milo, atlas, orion
- Supports 23 languages including English, Spanish, German, and Japanese
- Language detection defaults to English for Latin-script text
Response Formats
The API returns the synthesized audio file directly in the response body, allowing you to save the output immediately. You can choose from five standard formats: MP3, WAV, OPUS, FLAC, and PCM, depending on your quality and bandwidth needs. Each generated file includes an inaudible watermark to identify it as synthetic speech.
Audio Formats Available
Select your preferred format via the response_format field in your request. MP3 offers the best balance of quality and file size, while WAV and FLAC provide lossless audio. PCM is useful for raw data processing, and OPUS offers high efficiency.
JSON Response Structure
The API returns a binary audio stream rather than a JSON object. If you use the OpenAI SDK or standard HTTP clients, the response body contains the raw audio bytes. Metadata such as character count and model used is handled via HTTP headers or your billing dashboard, not the response payload.
Error Handling
Errors are returned as standard HTTP status codes (4xx or 5xx) with a JSON body describing the issue. Common errors include invalid API keys, rate limit exceeded, or input text exceeding 4096 characters. Failed requests are free, so you can retry or adjust your input without incurring costs.
- 401 Unauthorized: Invalid or expired API key
- 429 Too Many Requests: Rate limit exceeded (60 req/min)
- 400 Bad Request: Invalid parameters or text length
Rate Limits
The API enforces strict rate limits to ensure stable generation performance. Each API key is capped at 60 requests per minute once your account is active. This limit applies uniformly across all endpoints, so monitor your aggregate usage to avoid interruptions during high-volume campaigns.
Requests are processed sequentially, meaning longer texts may queue briefly if the system is busy. Understanding these limits helps you plan your audio generation workflows efficiently, especially when producing content for TikTok or Reels at scale.
Requests Per Minute
Your active API key allows up to 60 requests per minute. This cap includes all speech generation calls and helps maintain consistent quality across your production pipeline.
If you exceed this threshold, subsequent requests will be throttled until the window resets. Plan your batch sizes accordingly to avoid unnecessary delays in your content creation process.
- Limit: 60 requests/minute per key
- Applies to all API endpoints
- Sequential processing may cause minor queues
Pre-Top-Up Limits
New accounts without a top-up start with a lower limit of 10 requests per minute. This ensures fair usage while you test the service with your free trial credit.
Once you add funds via USDT (TRC-20), your limit increases to the full 60 requests per minute automatically within minutes.
- Standard limit: 60 req/min
- Pre-top-up limit: 10 req/min
- Auto-updates after confirmed payment
Handling Throttling
When throttled, the API returns a 429 status code. Implement exponential backoff in your integration to retry requests gracefully.
Since short phrases take a few seconds to generate, batch your requests with small delays to stay within limits without sacrificing throughput.
Monitor your usage dashboard to track your current rate limit status and adjust your generation strategy as needed.
- Use 429 status code detection
- Implement exponential backoff
- Monitor usage dashboard for stats

Example Requests
Generate audio instantly with a simple cURL command. Replace YOUR_API_KEY with your key from /get-api-key/ and send your text to the speech endpoint. The API returns the audio file directly in the response, ready for download or immediate playback in your TikTok or Reels workflow.
cURL Example
Use this command to generate a 5-second clip. It sends a POST request to the API with your authentication token and text payload. The response contains the audio data in your chosen format.
- Replace
YOUR_API_KEYwith your actual key. - Adjust
inputtext to your script. - Set
response_formatto mp3 or wav.
OpenAI SDK Example
Since the endpoint mimics the OpenAI speech endpoint, you can reuse the official OpenAI SDK. Just change the base_url to https://api.playhs55.com/v1 and use your ReelVoic key. This allows seamless integration into existing Python or Node.js projects without learning a new client library.
- Set
base_urltohttps://api.playhs55.com/v1. - Use standard
openai.Audiomethods (or the appropriate method for your SDK version). - Pass your
tts-...key as the bearer token.
Python Example
For agency pipelines, use the requests library for lightweight integration. This example demonstrates sending a POST request with JSON headers. Handle the response by writing the binary content to a file, ensuring your automation script can process multiple voice-overs efficiently.
- Import
requestsandjson. - Set headers with
Authorization: Bearer YOUR_KEY. - Write
response.contentto a local file.
Error Codes
Errors return standard HTTP status codes with a JSON body containing an error object. This structure allows automated pipelines to distinguish between temporary issues and permanent failures.
Common Errors
HTTP 401 Unauthorized indicates an invalid or expired API key. HTTP 500 errors are rare but may occur during peak load.
Rate Limit Errors
HTTP 429 Too Many Requests occurs when you exceed 60 requests per minute (or 10/min before top-up). The response includes a Retry-After header specifying seconds to wait. Implement exponential backoff to handle queue delays gracefully.
- 60 requests/minute limit per key
- 10 requests/minute pre-top-up
- Retry-After header provided
Input Validation Errors
HTTP 400 Bad Request returns if input exceeds 4096 characters, voice is invalid, or speed is out of range (0.25–4.0). Ensure text fits within limits or split it beforehand to avoid partial failures.
- Max 4096 characters per request
- Valid voices: aria, nova, luna, sage, felix, milo, atlas, orion
- Speed range: 0.25 to 4.0
Best Practices
For agencies processing high-volume voice-overs for TikTok and Shorts, splitting long scripts ensures consistent quality and predictable costs. The API accepts up to 4,096 characters per request; texts exceeding this limit should be divided into parts and the resulting audio files joined afterward.
Implementing robust error retries is essential because requests are processed sequentially. Under heavy load, your synthesis job may wait in a queue, potentially causing timeouts. Use exponential backoff to handle transient failures, ensuring your pipeline remains resilient without wasting credits on duplicate generations.
Splitting Long Texts
Break scripts into chunks of 4,096 characters or fewer. Since typical speed is roughly real-time, splitting helps manage latency for long-form content. Join the resulting audio files client-side or via a simple concatenation step to maintain narrative flow.
Error Retries
Requests are processed one after another, so under load a request may wait in a queue. Implement retry logic with exponential backoff to handle temporary delays or network hiccups. Remember that failed requests are free, so retries do not incur extra cost if they ultimately fail.
Caching Strategies
Cache generated audio files locally or on your CDN to avoid regenerating identical content. Since input text determines the output, storing the mapping between text hashes and audio files reduces API calls.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. We create vertical video content optimized for short-form platforms like TikTok, Reels, and Shorts.
23 languages
Any voice speaks any of these languages.
