Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.playsv77.com/v1. You send POST requests to https://api.playsv77.com/v1/audio/speech to generate audio. This endpoint accepts JSON bodies containing your text, voice selection, and format preferences. All other endpoints, such as retrieving voices or models, are accessed relative to this base URL.
How do I authenticate my requests?
Include your API key in the Authorization header as Bearer tts-... . Each account has one active key at a time. You can issue a new key at any time via the dashboard; the old key stops working immediately. Ensure your key is valid before sending requests to avoid authentication errors.
What models are available?
Two models are available: tts-1 and tts-1-hd. Both use the same engine and price. Choose tts-1 for standard generation or tts-1-hd for higher quality. The model parameter is required in your request body. Both models support all available voices and languages, offering consistent performance across your use cases.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.playsv77.com/v1. Use your AssistVoice API key for authentication. The request shape matches the OpenAI speech endpoint exactly. This allows you to integrate AssistVoice into existing OpenAI-based workflows without significant code changes or custom client implementations.
What are the rate limits?
The limit is 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. If you exceed this, requests may be queued or rejected. Ensure your application handles rate limit errors gracefully. For high-volume use, consider batching requests or implementing exponential backoff strategies.
How do I handle errors?
Failed requests are free, and the charge is returned in full. Monitor response status codes to detect failures. If synthesis fails, no characters are deducted from your balance. Implement retry logic for transient errors. Check your key validity and rate limit status if errors persist. Review the response body for specific error details.
What audio formats are supported?
Supported formats are mp3, wav, opus, flac, and pcm. Specify the desired format using the response_format parameter in your request. Each format serves different use cases, from web playback to high-fidelity storage. The API returns the audio file directly in the response, allowing immediate playback or storage.
How do I specify a voice?
Use the voice parameter with one of eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narrators to deep documentary styles. Select the voice that best fits your content. You can switch voices dynamically between requests to vary the output.
What is the character limit per request?
Each request supports up to 4096 characters of input text. For longer texts, split them into parts of this size and join the resulting audio files. Spaces and punctuation count toward the character limit. This limit ensures efficient processing and consistent generation times for standard-length inputs.
How do I set the language?
Use the optional language parameter with an ISO code. If omitted, the language is guessed from the script, defaulting to English for Latin text. For non-English Latin-script text, explicitly set the language to ensure correct pronunciation. Supported languages include Arabic, Chinese, English, French, German, and others listed in the API docs.
Can I change the speed of the speech?
Yes, adjust the speed using the speed parameter, ranging from 0.25 to 4.0. The default speed is 1.0. Faster speeds reduce generation time, while slower speeds may improve clarity for accessibility use cases. This feature allows fine-tuning the output to match your specific application requirements.
What happens if I exceed the rate limit?
Requests are processed sequentially, so under load, a request may wait in a queue. If you exceed the limit, subsequent requests may be delayed or rejected. Implement retry logic with exponential backoff. Monitor your usage via the dashboard to stay within limits.
How do I get a list of available voices?
Send a GET request to /v1/voices. This endpoint returns details about all available voices, languages, formats, and pricing. Use this information to select the best voice for your content. The response includes metadata about each voice, helping you make informed decisions about your TTS implementation.
Is the API compatible with OpenAI SDKs?
Yes, the API is compatible with OpenAI SDKs. Change the base_url to https://api.playsv77.com/v1 and use your AssistVoice key. The request shape matches the OpenAI speech endpoint. This compatibility allows seamless integration into existing OpenAI-based applications without requiring custom client code or significant refactoring of your existing logic.
First request
curl
curl https://api.playsv77.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.playsv77.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.playsv77.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
Access the AssistVoice API using a Bearer token in the Authorization header. This single key authenticates all requests to the speech endpoint and ensures secure, tracked usage of your account's character balance.
Bearer Token
Include your key as Authorization: Bearer tts-... in every request. The token verifies your identity and deducts characters from your active balance at the rate of $0.01 per 1,000 characters (or $10 per 1 million characters).
- Format:
Authorization: Bearer tts-your_key_here - Sent in the HTTP header for all API calls
Single Active Key
Each account maintains one active API key. If you generate a new key, the previous one becomes invalid immediately. This simplifies security for assistive device deployments by ensuring only one credential is valid at any time.
Key Management
Manage your key directly on the /get-api-key/ dashboard. You can view your current balance, usage statistics, and issue a new key instantly without downtime, ensuring continuous operation for your elderly care applications.
- View balance and usage on the dashboard
- Issue new keys with immediate invalidation of old ones
Endpoints Overview
The AssistVoice API provides three core endpoints to handle speech synthesis and configuration. The primary endpoint processes text inputs and returns audio files, while the secondary endpoints expose available voices and model details for seamless integration.
POST /v1/audio/speech
This endpoint accepts your text and returns an audio file. It follows the same request shape as the OpenAI speech endpoint, allowing you to use existing OpenAI SDKs by simply updating the base URL. You can specify the model, voice, language, and audio format in a single JSON payload.
- Endpoint: POST https://api.playsv77.com/v1/audio/speech
- Accepts JSON body with model, input, voice, and response_format
- Returns audio file directly in the response
GET /v1/voices
Use this endpoint to retrieve a list of available voices, supported languages, and audio formats. It helps you verify which voices are active and determine the correct parameters for your synthesis requests before sending data.
- Lists all 8 available voice presets
- Shows supported languages and formats
- Returns current pricing and availability status
GET /v1/models
This endpoint returns the available TTS models, currently "tts-1" and "tts-1-hd". Both models use the same engine and pricing, allowing you to switch between standard and high-quality audio without changing your pricing structure.
- Returns available model identifiers
- Confirms pricing parity between tts-1 and tts-1-hd
- Provides model metadata for integration
Request Parameters
Configure the synthesis parameters to match your assistive device or elderly care app requirements. The API accepts standard text input and allows precise control over voice, model, and output format to ensure optimal audio clarity and character accuracy.
Model Selection
Choose between tts-1 for standard processing or tts-1-hd for higher fidelity. Both models use the same engine and pricing structure, allowing you to switch without changing your integration logic.
Input Text
Submit plain text in the input field, limited to 4096 characters per request. Spaces and punctuation count toward the character limit. For longer content, split the text into chunks and join the resulting audio files.
Voice Selection
Select from eight distinct presets to suit your application's tone. Female voices include aria (warm, clear narrator), nova (bright, upbeat), luna (soft, storytelling), and sage (calm, instructional). Male options are felix (energetic, promo), milo (friendly, conversational), atlas (neutral, news), and orion (deep, documentary).
Response Formats
Select the output format that best suits your assistive device or elderly care application’s playback requirements. Each format balances file size, compatibility, and audio fidelity differently, allowing you to optimize for bandwidth or quality.
MP3
MP3 is the default and most widely supported format. It offers a good balance between file size and sound quality, making it ideal for mobile apps and web players where bandwidth conservation is important.
WAV
WAV provides uncompressed, high-quality audio. Use this format when you need pristine sound quality for playback on devices that do not support lossy compression or when you plan to further process the audio file.
FLAC, OPUS, PCM
FLAC offers lossless compression, reducing file size without quality loss. OPUS is efficient for low-bandwidth transmission. PCM provides raw, uncompressed audio data, useful for immediate hardware playback without decoding overhead.
- FLAC: Lossless, smaller than WAV
- OPUS: Efficient for low bandwidth
- PCM: Raw, uncompressed data
Rate Limits
Our API enforces strict rate limits to ensure stability during high-volume synthesis. Each API key is capped at 60 requests per minute, which is sufficient for most batch processing and real-time assistive device applications. Requests are processed sequentially, meaning complex generations may take slightly longer under load.
New accounts start with a lower limit of 10 requests per minute until the first top-up is confirmed. This prevents accidental bursts from draining your initial free trial balance before you verify your payment method.
60 Requests per Minute
Once you add funds, your limit increases to 60 requests per minute. This throughput is designed to handle typical startup workloads, such as generating audio for elderly care apps or assistive hardware, without requiring complex queue management on your end.
10 Requests per Minute (Initial)
Before your first top-up, you are limited to 10 requests per minute. This allows you to test the API’s quality and integration without risking excessive usage during your free trial period.
Queue Processing
Requests are processed one after another. If you send multiple requests rapidly, they will be queued and executed in order. Long texts may take time to synthesize, but the system ensures each request is completed before moving to the next, preventing data corruption.
- Requests are sequential, not parallel.
- Queue ensures no data loss.
- No parallel burst allowed.

Error Handling
Understanding error responses ensures your assistive device or elderly care app handles synthesis failures gracefully without crashing. AssistVoice returns standard HTTP codes to indicate the status of each request, allowing your integration to distinguish between temporary network issues and permanent configuration errors.
Common Error Codes
The API returns specific HTTP status codes to help you debug integration issues. A 400 Bad Request indicates invalid JSON, missing required fields, or text exceeding the 4096-character limit. A 401 Unauthorized error occurs if the Bearer token is missing or invalid, while a 429 Too Many Requests signal means you have exceeded the 60 requests per minute rate limit.
Retry Logic
For transient errors like 429 or 5xx server errors, implement exponential backoff in your client. Since requests are processed sequentially during high load, short pauses between retries prevent overwhelming the queue. Avoid immediate rapid retries, as this may worsen congestion and delay audio generation for your users.
- Retry on 429 with increasing delays.
- Retry on 500-503 errors.
- Do not retry 400 or 401 errors without input correction.
Failed Request Refunds
If synthesis fails due to a server-side error, the charge is returned in full to your balance. Failed requests do not consume your character allowance. This ensures you only pay for successfully generated audio files, maintaining transparent per-character pricing even during occasional service hiccups.
OpenAI SDK Integration
Integrating AssistVoice with existing projects is straightforward because the API mirrors the structure of the OpenAI speech endpoint. You do not need a custom client library; simply point your existing OpenAI SDK to our base URL and provide your API key. This allows startups to swap providers with minimal code changes, leveraging familiar tools for assistive device and elderly care applications.
The single active key model ensures consistent access control, while the standardized request shape means your code remains portable. By updating just the base URL and headers, you gain access to clear, natural speech voices without adopting a new ecosystem or learning a proprietary SDK format.
Base URL Change
Update your SDK configuration to use https://api.playsv77.com/v1 as the base URL. This directs all requests to our infrastructure while maintaining the standard endpoint paths. Ensure your authorization header includes your tts-... bearer token.
This change enables immediate compatibility with the 8 voice presets and 23 supported languages. Your existing logic for handling text inputs and audio outputs remains valid, requiring only this single configuration adjustment to switch from any OpenAI-compatible provider.
SDK Compatibility
The official OpenAI SDKs work seamlessly with our API. Since we adhere to the same request shape, you can use any language supported by the OpenAI client libraries (Python, Node.js, etc.).
This compatibility extends to error handling and response parsing. Your application will receive audio files in the specified format (mp3, wav, opus, flac, or pcm) without needing custom deserialization logic for our specific JSON structure.
Code Example
```python import openai client = openai.OpenAI( base_url="https://api.playsv77.com/v1", api_key="tts-your-api-key-here" ) with client.audio.speech.create( model="tts-1", voice="aria", input="Hello, this is a test of the AssistVoice API for elderly care apps.", response_format="mp3" ) as response: response.stream_to_file("output.mp3") ``` This Python snippet demonstrates the minimal code required to generate speech. Replace the API key and adjust the voice or model as needed. The response returns the audio file directly, which you can save to disk.
Quick Start with cURL
Generate audio instantly with a single command. The AssistVoice API accepts plain text and returns synthesized speech files, making it easy to test voice quality before full integration.
This quick start demonstrates the core workflow: sending a request, receiving the audio file, and verifying the output format for your assistive device or app.
cURL Example
Use this command to generate speech. Replace <YOUR_API_KEY> with your key from the dashboard.
The command sends the request to the API base URL and saves the output to speech.mp3.
- Ensure your key starts with
tts-. - The endpoint is
https://api.playsv77.com/v1/audio/speech. - Set
Content-Type: application/json.
JSON Body Structure
The request body requires a model, input text, and voice selection. The input field supports up to 4096 characters.
You can optionally specify a language code or speed adjustment between 0.25 and 4.0.
model: "tts-1" or "tts-1-hd".voice: e.g., "aria", "nova", "felix".input: your text string.response_format: "mp3" (default).
Audio Output
The response returns the audio file directly in the body. If the request fails, a JSON error object is returned with no charge.
Generated files contain an inaudible watermark to identify synthetic speech. You can choose MP3, WAV, FLAC, OPUS, or PCM formats.
- MP3 is recommended for general use.
- WAV provides uncompressed quality.
- FLAC offers lossless compression.
- PCM is raw audio data.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Input text is used exclusively for audio generation and never for model training.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- Tether (USDT)
- LibriTTS-R corpus (OpenSLR 141)
- W3C WAI: making audio and video accessible
- OpenAI API reference: create speech
- Creative Commons Attribution 4.0
- TRON developer hub: TRC-20
- Python documentation
- Node.js documentation
- curl documentation
- ISO 639 language codes
- LibriVox public-domain audiobooks
