Frequently asked questions
How do I generate an API key for the first time?
Navigate to /get-api-key/ and sign up using Google or an email and password combination. The dashboard displays your unique API key immediately. Each account holds one active key. You can issue a new key at any time, which instantly invalidates the previous one.
Can I use the official OpenAI SDK with this API?
Yes. The request shape matches the OpenAI speech endpoint exactly. You can use the official OpenAI SDKs by simply changing the base_url to https://api.play29p.com/v1 and providing your NodeVoice API key. This allows seamless integration into existing Python or JavaScript projects without custom client code.
What is the correct base_url for the OpenAI SDK?
Set your base_url to https://api.play29p.com/v1. This endpoint handles all TTS requests. Ensure your Authorization header uses the format Bearer tts-... with your specific key. The SDK will then route requests to the correct NodeVoice infrastructure for audio synthesis.
How do I specify a language that is not detected automatically?
Include the language parameter in your request body with the ISO code. If omitted, the system guesses the language, defaulting to English for Latin script. Explicitly setting the language ensures correct pronunciation for non-English texts, such as German or Japanese, regardless of the script used.
What happens if I send a request with an invalid voice name?
The API will return an error response indicating the invalid voice. Since the system only accepts eight specific presets, any other name triggers a rejection. No characters are consumed from your balance for this failed request, ensuring you are not charged for invalid parameters.
Does the API support streaming responses?
No. The API does not support streaming, WebSocket connections, or real-time partial audio delivery. You must send a POST request to /v1/audio/speech and wait for the complete audio file to be returned.
How do I handle large texts exceeding 4096 characters?
Split your input text into chunks of up to 4096 characters each. Send separate requests for each chunk and receive individual audio files. You must then join these audio files client-side to create the final output. This ensures compliance with the single-request character limit.
Is the Authorization header case-sensitive?
A: Yes. You must use the exact header format: Authorization: Bearer tts-... followed by your key. Ensure no extra spaces or typos exist in the token to avoid authentication failures.
What is the maximum speed value I can set?
The maximum speed value is 4.0. The supported range is 0.25 to 4.0. Values outside this range will result in a request error. Adjusting speed allows you to optimize audio length for bandwidth-constrained IoT devices without requiring post-processing of the generated audio files.
Do I need to install a specific SDK for Python?
No. You can use the official OpenAI SDK or plain HTTP requests. There is no proprietary NodeVoice SDK.
How can I verify if a request was successful?
Check the HTTP status code of the response. A successful request returns a 200 OK status along with the audio file. Failed requests return an error code and are free, with no charge to your balance. Inspect the response body for detailed error messages if needed.
Are there limits on the number of voices I can use?
No. You can use all eight available voices: aria, nova, luna, sage, felix, milo, atlas, and orion. There is no limit on switching between voices per request or over time. Each voice supports all 23 languages, allowing flexible audio generation for diverse smart home scenarios.
Can I use the same API key for multiple projects?
Yes. One active key per account is issued, and you can use it across multiple projects or devices. The rate limit of 60 requests per minute applies per key. Monitor your usage via the dashboard to ensure you stay within the limits for all integrated systems.
First request
curl
curl https://api.play29p.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.play29p.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.play29p.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 and Keys
Authentication for the NodeVoice API relies on a single active Bearer token per account. You generate this key via the /get-api-key/ dashboard page, which displays your current credentials, balance, and usage statistics. The key format begins with the prefix "tts-" and is included in the HTTP header for every request.
Generating API Keys
Accounts are created via Google Sign-In or email registration on the /get-api-key/ page. Upon sign-up, you receive a unique API key valid for all endpoints. The dashboard immediately displays your key, initial balance, and a ready-to-use cURL example for verification.
- Access the /get-api-key/ page after signing in.
- Select Google or Email/Password registration method.
- Copy the displayed key starting with 'tts-'.
Bearer Token Format
Include your key in the Authorization header of every API request. Use the standard format: Authorization: Bearer tts-xxxxxxxxxxxxxxxxxxxxxxxx. Ensure no extra spaces or quotes surround the token value to prevent authentication failures during synthesis requests.
Key Rotation Policy
You may issue a new key at any time directly from the dashboard. When a new key is generated, the previous key becomes invalid immediately. This ensures that lost or compromised credentials are deactivated instantly without waiting for a session timeout.
Speech Endpoint Overview
The core synthesis engine is accessed via a standard HTTP POST request to the /v1/audio/speech endpoint. This endpoint accepts JSON payloads containing the source text and configuration parameters, processing them to generate high-fidelity audio files suitable for IoT device playback.
POST /v1/audio/speech
Send your request to https://api.play29p.com/v1/audio/speech. The endpoint accepts JSON bodies and returns the generated audio file directly in the response body, allowing straightforward integration into embedded systems and backend services without complex streaming logic.
- Method: POST
- Content-Type: application/json
- Endpoint: /v1/audio/speech
Request Body Structure
The request body requires the input text (max 4096 characters), the model identifier (tts-1 or tts-1-hd), and the voice preset. Optional fields include response_format, speed, and language. The system automatically handles character counting and billing based on the input length.
Response Format
Upon successful processing, the API returns the audio file in the specified format (mp3, wav, opus, flac, or pcm). Failed requests return standard HTTP error codes with a JSON error message, and no charge is applied for synthesis failures.
Parameters and Configuration
Configure synthesis parameters to align audio output with embedded device constraints. Select between the standard "tts-1" or high-definition "tts-1-hd" model, both utilizing the same engine and pricing tier. The model selection does not affect the endpoint structure or request body format.
Model Selection
Both "tts-1" and "tts-1-hd" accept identical request shapes. Choose based on bandwidth availability and latency requirements for your IoT hardware. Pricing remains constant at $10 per 1 million characters regardless of the model chosen.
Voice Presets
Assign one of eight deterministic voice presets to generate consistent audio. Female voices include aria, nova, luna, and sage; male voices include felix, milo, atlas, and orion. Each voice is suited for specific interaction contexts, from news updates to conversational prompts.
- aria: warm, clear narrator
- nova: bright, upbeat
- luna: soft, storytelling
- sage: calm, instructional
- felix: energetic, promo
- milo: friendly, conversational
- atlas: neutral, news
- orion: deep, documentary
Speed and Language Settings
Adjust playback speed between 0.25 and 4.0 to fit device processing limits. Specify the language using an ISO code to ensure correct pronunciation, especially for non-English Latin-script text where auto-detection defaults to English. Omitting the field relies on script-based guessing.
- Speed range: 0.25–4.0
- Language: optional ISO code
- Default language detection: English for Latin script
Supported Audio Formats
NodeVoice supports five standard audio formats for flexible integration. MP3 and WAV are optimal for general playback, while Opus and FLAC provide efficient compression and lossless quality respectively. PCM raw audio is available for systems requiring uncompressed byte streams.
MP3 and WAV Options
MP3 offers balanced file size and compatibility for most IoT devices. WAV provides uncompressed, high-fidelity audio suitable for local storage or immediate playback without decoding overhead. Both formats are universally supported across modern embedded systems.
- MP3: Compressed, widely compatible, smaller file size.
- WAV: Uncompressed, high fidelity, standard for local playback.
Opus and FLAC Support
Opus delivers efficient compression, ideal for bandwidth-constrained IoT networks. FLAC provides lossless quality for archival or high-fidelity requirements. Both formats ensure clear audio reproduction while optimizing storage or transmission costs.
- Opus: High compression ratio, suitable for bandwidth-constrained IoT networks.
- FLAC: Lossless compression, perfect quality retention, larger file size.
PCM Raw Audio
PCM provides raw, uncompressed audio data in byte format. It is ideal for embedded systems that handle their own audio processing or require precise sample control. This format eliminates decoding latency, ensuring deterministic performance for real-time applications.
- PCM: Raw byte stream, suitable for systems requiring uncompressed byte streams.
- Ideal for custom audio pipelines and embedded hardware.
Error Handling and Status Codes
NodeVoice returns standard HTTP status codes to indicate the outcome of each synthesis request. A 200 OK response confirms that the audio file has been generated and is attached to the response body. Errors are communicated via 4xx or 5xx codes, allowing your IoT gateway or smart home controller to handle failures gracefully without crashing.
Common HTTP Errors
The API uses 401 Unauthorized if the Bearer token is missing or invalid, and 400 Bad Request for malformed JSON bodies. A 429 Too Many Requests indicates you have exceeded your quota. These errors are deterministic, ensuring predictable behavior for embedded systems.
- 401: Invalid or expired API key
- 400: Malformed request body or missing fields
- 429: Rate limit exceeded
- 500: Internal server error during synthesis
Rate Limit Exceeded
Each API key is limited to 60 requests per minute after initial top-up, with a strict 10 RPM limit for new accounts before the first deposit. If you exceed this threshold, the API returns a 429 status code. Failed requests do not consume your character balance.
- Standard limit: 60 requests per minute per key
- New account limit: 10 requests per minute
- 429 status returned when limit is reached
- No charge for failed or throttled requests
Invalid Input Handling
If the input text exceeds 4096 characters, the request will fail with a 400 error. Unsupported characters or invalid voice names also trigger this status. Ensure your IoT device or edge device validates text length before sending the POST request to avoid unnecessary network overhead.
- Maximum input length: 4096 characters
- Includes spaces and punctuation in character count
- Invalid voice ID returns 400 error
- Empty input text returns 400 error

SDK Integration Examples
The API mirrors the OpenAI speech endpoint structure, allowing existing integrations to adapt with minimal code changes. By updating the base URL, developers can leverage standard OpenAI SDKs for NodeVoice without rewriting request logic.
This approach ensures deterministic pricing and standard-compliant payloads for embedded systems. The SDK handles JSON serialization and authentication headers automatically, reducing boilerplate in IoT firmware or backend services.
OpenAI SDK Configuration
Initialize the client with your API key. The key format is tts-... and must be passed via the Authorization: Bearer header. The SDK manages the header injection, ensuring secure transmission to https://api.play29p.com/v1.
Base URL Modification
Set the base_url parameter to https://api.play29p.com/v1. This redirects all requests to NodeVoice’s infrastructure while maintaining the standard request shape. No custom client logic is required for routing.
Python and Node.js Snippets
Use the official OpenAI library for both Python and Node.js. Pass the custom base URL during initialization. The input field accepts up to 4096 characters. The response returns an audio file, ready for playback or storage in your smart home device.
- Python:
openai.OpenAI(base_url='https://api.play29p.com/v1', api_key='tts-...') - Node.js:
new OpenAI({ baseURL: 'https://api.play29p.com/v1', apiKey: 'tts-...' })
cURL Command Examples
The API accepts standard JSON payloads via POST requests. You must include your Bearer token in the Authorization header to authenticate each request to the endpoint.
Basic Speech Request
Send text to the default model using the following command. Replace YOUR_API_KEY with your generated key. The system returns a binary audio file.
- curl -X POST "https://api.play29p.com/v1/audio/speech" \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}'
Custom Speed and Format
Adjust playback speed between 0.25 and 4.0. Select formats like WAV or FLAC for high fidelity in IoT storage.
- curl -X POST "https://api.play29p.com/v1/audio/speech" \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1-hd", "input": "System ready", "voice": "atlas", "speed": 1.5, "response_format": "wav"}'
Language Specification
Explicitly define the language ISO code to ensure correct synthesis for non-English texts. This prevents automatic English fallback for Latin-script inputs.
- curl -X POST "https://api.play29p.com/v1/audio/speech" \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1", "input": "Guten Tag", "voice": "sage", "language": "de", "response_format": "mp3"}'
Rate Limits and Quotas
NodeVoice enforces a standard rate limit of 60 requests per minute for each active API key. This capacity supports steady-state generation for IoT devices and embedded systems, ensuring consistent audio delivery without overwhelming the synthesis engine.
60 Requests Per Minute
Each API key is permitted 60 requests per minute under normal operation. This limit applies to all successful and failed synthesis attempts, ensuring fair usage across all accounts without distinction based on model type.
Initial 10 RPM Limit
New accounts begin with a reduced limit of 10 requests per minute. This restriction remains in effect until the first top-up is processed. Once a minimum USDT transfer of $5 is confirmed on the TRON network, the limit automatically increases to 60 RPM.
Queue Management
Requests are processed sequentially. If the service experiences high load, additional requests may wait in a queue before synthesis begins. Longer texts are split into parts, which are then joined; this sequential processing may introduce latency during peak usage periods.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This creates a more consistent user experience across different devices within a smart home or industrial network without manual reconfiguration.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- Node.js documentation
- OpenAI API reference: create speech
- openai-node on GitHub
- LibriVox public-domain audiobooks
- MDN: Web Speech API
- LibriTTS-R corpus (OpenSLR 141)
- W3C WAI: making audio and video accessible
- IETF RFC 7845: Ogg Opus
- FFmpeg documentation
- Creative Commons Attribution 4.0
- TRON developer hub: TRC-20
