Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or an email and password. Accounts are specific to this site. Once registered, your dashboard displays your active API key, current balance, and usage statistics immediately, allowing you to start making requests without waiting for approval.
What is the base URL for the API?
The API base URL is https://api.playfk9.com/v1. You send POST requests to https://api.playfk9.com/v1/audio/speech for synthesis. Other endpoints like /v1/voices are accessed relative to this same base URL, ensuring consistent routing for all your integration calls.
Can I use the OpenAI SDK with this API?
Yes. The request shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.playfk9.com/v1 and providing your BotVoice key. This allows you to integrate quickly using familiar code structures without learning a new client library.
What is the maximum input character limit?
Each request supports up to 4096 characters in the input field. If your text exceeds this limit, you must split it into parts of 4096 characters or fewer. The API does not handle long-text splitting automatically, so your application should manage chunking and audio joining.
How do I specify the language in the request?
Include the optional 'language' field with an ISO code in your JSON body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always set the language parameter to ensure correct pronunciation.
Does the API support streaming audio?
No, the API does not support streaming, WebSockets, or real-time partial audio. You send a POST request and receive the complete audio file in the response. This synchronous approach simplifies integration for voice assistants and chatbots that do not require real-time audio chunks.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so exceeding the limit may cause your request to wait in a queue. Failed requests do not incur charges, but successful ones count toward your limit.
Can I change the speed of the speech?
Yes, use the 'speed' field in your request body. The acceptable range is 0.25 to 4.0. This allows you to adjust the playback rate of the generated audio to fit your voice assistant’s pacing or chatbot interaction style without needing external audio processing tools.
How do I list available voices?
Send a GET request to /v1/voices. This endpoint returns details on all 8 voice presets, supported languages, formats, and pricing information. It provides the necessary data to select the appropriate voice for your specific use case before generating audio content.
Is there an endpoint to check balance?
Q: Is there an endpoint to check balance? A: The /v1/voices endpoint returns pricing information. You must handle splitting for texts longer than 4096 characters. The API processes each request independently. Your application should split the input text, send multiple requests, and then join the resulting audio files to create a continuous output for the user.
Do I need to handle audio file splitting?
No. The API accepts up to 4,096 characters per request. For longer texts, split your input into parts of this limit and join the resulting audio files. This ensures reliable synthesis without exceeding the character constraint for each individual API call.
What is the difference between tts-1 and tts-1-hd?
Both models use the same engine and price. Choose 'tts-1' for standard quality or 'tts-1-hd' for high-definition audio. Authentication requires an 'Authorization' header with 'Bearer tts-...' followed by your active API key. You can generate a new key anytime via the dashboard, which instantly invalidates the previous one. Keep your key secure in your application environment.
How do I authenticate with Bearer token?
Q: How do I authenticate with Bearer token? A: Include your BotVoice API key in the Authorization header as Bearer tts-.... Since the request shape matches the OpenAI speech endpoint, you can use the official OpenAI SDKs by setting the base URL to https://api.playfk9.com/v1 and providing your key for authentication.
First request
curl
curl https://api.playfk9.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.playfk9.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.playfk9.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 access by generating a key on the /get-api-key/ page. Sign in with Google or create an account with email and password. The dashboard displays your active key, usage stats, and a ready-to-use cURL example for immediate testing.
API Key Generation
Create your key instantly via the dashboard. Each account holds one active key. Keys are unique to the site domain.
Bearer Token Usage
Include your key in the request header as Authorization: Bearer tts-.... Use this header for all API calls, including speech synthesis and model checks.
- Format:
Authorization: Bearer YOUR_KEY - Case-sensitive header value
- Valid for all endpoints
Key Rotation Policy
Generate a new key at any time via the dashboard. The previous key stops working immediately upon issuance. This ensures clean access control without downtime.
Speech Endpoint
Send your text to the speech endpoint to receive an audio file. The API accepts standard JSON payloads, allowing you to integrate directly using the OpenAI SDK or any HTTP client by adjusting the base URL.
POST Request Structure
The endpoint is POST https://api.playfk9.com/v1/audio/speech. You must send a JSON body containing the model, input text, and voice selection. The response returns the audio file directly in the requested format.
- Endpoint: POST /v1/audio/speech
- Content-Type: application/json
Required Fields
Every request must include model, input, and voice. The model accepts either tts-1 or tts-1-hd. The input field holds your text, limited to 4096 characters. The voice field requires one of the eight available preset IDs.
Optional Parameters
You can adjust response_format (mp3, wav, opus, flac, pcm) and speed (0.25–4.0). Use language with an ISO code to ensure correct pronunciation for non-English text. If omitted, the system guesses the language, defaulting to English for Latin script.
Voice Models
BotVoice provides two model presets, tts-1 and tts-1-hd, which use the same synthesis engine. You select the model via the model field in your JSON request body. This simple choice allows you to balance processing speed against audio quality without managing complex infrastructure.
tts-1 Model
The tts-1 preset delivers standard quality audio optimized for speed. It is ideal for voice assistants and chatbots where low latency is critical for a natural conversational flow.
tts-1-hd Model
The tts-1-hd preset offers enhanced audio fidelity with richer detail. Use this model when clarity and nuance are prioritized over raw processing speed, such as in high-quality narration or premium voice experiences.
Model Price Difference
Both models are priced identically at $10 per 1 million characters. There is no cost premium for choosing the HD preset; you only pay for the characters processed, regardless of the model selected.
Available Voices
BotVoice provides eight distinct voice presets designed for clarity and consistency in voice assistants and chatbots. Each voice is derived from licensed LibriTTS-R recordings, ensuring high-quality synthetic speech suitable for conversational interfaces.
Female Voices List
Aria offers a warm, clear narrator tone ideal for general assistance. Nova provides a bright, upbeat voice for engaging interactions. Luna delivers a soft, storytelling quality for narrative content. Sage presents a calm, instructional style perfect for guided workflows.
- aria: warm, clear narrator
- nova: bright, upbeat
- luna: soft, storytelling
- sage: calm, instructional
Male Voices List
Felix brings an energetic, promo-ready tone for announcements. Milo offers a friendly, conversational style for natural dialogue. Atlas provides a neutral, news-like voice for factual delivery. Orion delivers a deep, documentary tone for immersive experiences.
- felix: energetic, promo
- milo: friendly, conversational
- atlas: neutral, news
- orion: deep, documentary
Voice Selection Guide
Select voices based on your application's personality. Use Milo or Aria for conversational agents, and Atlas or Sage for informational commands. All voices support any of the 23 supported languages, allowing you to maintain consistent character across regions.
Response Formats
BotVoice returns audio in standard formats compatible with most voice assistant and chatbot pipelines. You can choose between compressed MP3, uncompressed WAV, or efficient OPUS and FLAC files depending on your latency and quality needs.
MP3 Output
MP3 is the default format and offers the best balance between file size and compatibility. It is a standard format for voice assistant integrations.
WAV Output
Choose WAV for uncompressed, high-fidelity audio. This format is suitable when your downstream processing requires raw audio data or when maximum quality is prioritized over transfer size.
OPUS and FLAC
OPUS and FLAC are available formats for audio output. Use these formats if your infrastructure supports these specific codecs for optimized performance.

Language Support
BotVoice supports 23 languages, allowing any voice to speak any supported language. You can explicitly set the language using an ISO code in the request to ensure correct pronunciation, especially for non-English text in Latin script. This avoids ambiguity when the script is shared across languages.
If you omit the language field, the API guesses it from the text script. Latin text defaults to English. Explicitly setting the language is recommended for languages like Greek, Hebrew, or Hindi to ensure accurate synthesis without manual guesswork.
ISO Code Usage
Pass the language parameter with a valid ISO 639-1 code (e.g., de for German, ja for Japanese). This ensures the TTS engine applies the correct phonetic rules and prosody for that specific language, regardless of the voice selected.
Using explicit codes is critical for texts containing mixed scripts or when the default language guess might be incorrect. It guarantees consistent output quality across different regions and dialects.
- Use standard ISO 639-1 codes for clarity.
- Explicit codes prevent misinterpretation of shared scripts.
- Recommended for non-English Latin text.
Automatic Language Detection
When the language field is omitted, the API infers the language from the input text script. Latin script text defaults to English if no other signal is detected. Cyrillic, Greek, or CJK characters trigger the respective language models automatically.
This feature simplifies integration for single-language applications but may cause errors if the input text is ambiguous or mixed. For production voice assistants, explicit language setting is safer.
- Latin text defaults to English.
- Script detection handles Cyrillic, Greek, CJK.
- Use explicit codes for mixed texts.
Supported Languages List
The API supports 23 languages, including major global languages and regional variants. Any voice preset can speak any of these languages, allowing you to maintain consistent voice character across multilingual apps.
Unsupported languages include Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali, and others not listed below. Check the list before integrating regional content.
- Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
Rate Limits
The API enforces a standard rate limit of 60 requests per minute per API key. This cap applies to all synthesis endpoints and helps maintain service stability during peak usage. If you exceed this threshold, subsequent requests will be rejected until the window resets.
For long-form content, split your text into chunks of up to 4096 characters and process them sequentially. Since requests are handled one after another, heavy concurrent load may cause queuing delays, so plan your batch sizes accordingly to avoid hitting the rate limit.
Requests Per Minute
The standard limit is 60 requests per minute. This applies to every active API key associated with your account. If you send more than 60 requests in a 60-second window, the API returns a 429 Too Many Requests error.
- Standard limit: 60 requests/minute
- Applies per API key
- Returns 429 on excess
Initial Limit
New accounts start with a reduced limit of 10 requests per minute. This lower threshold remains in effect until you make your first top-up. Use this period to test integration stability before scaling up your voice assistant's request volume.
- Starts at 10 requests/minute
- Applies until first top-up
- Ensures initial load management
Limit After Top Up
After topping up your balance via USDT (TRC-20), your limit increases to the standard 60 requests per minute. Credits are added automatically within minutes of transfer. Once your balance is sufficient, you can immediately scale your voice app's usage without waiting for manual approval.
- Increases to 60 requests/minute
- USDT TRC-20 only
- Auto-credited within minutes
Error Handling
When integrating BotVoice into voice assistants, anticipating API responses ensures smooth user experiences. Errors typically stem from authentication issues, payload limits, or invalid configuration parameters. Understanding these common failure modes allows your chatbot to handle audio generation failures gracefully without breaking the conversation flow.
Common HTTP Errors
The API returns standard HTTP status codes to indicate request success or failure. A 401 Unauthorized error occurs if the Bearer token is missing, expired, or incorrect. A 429 Too Many Requests error indicates you have exceeded the 60 requests per minute limit per key.
- 401: Invalid or missing API key
- 429: Rate limit exceeded (60 req/min after top-up)
Character Limit Exceeded
Each request supports a maximum of 4096 characters in the input field. If your text exceeds this limit, the API will reject the request. For longer scripts, split the text into chunks of 4096 characters or less and concatenate the resulting audio files.
Invalid Voice ID
Requests fail if the specified voice does not exist in the system. Ensure you use one of the eight supported presets (e.g., aria, nova, felix). If you reference a voice not in the available list, the API returns an error indicating the voice ID is invalid.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Build conversational flows that feel human to delight users and drive engagement.
23 languages
Any voice speaks any of these languages.
