Frequently asked questions
How do I generate an API key?
Navigate to /get-api-key/ and sign up using Google or an email/password account. The dashboard displays your active API key immediately. You can issue a new key at any time, which instantly invalidates the previous one. Each account holds one active key for authentication.
What is the base URL for the API?
The API base URL is https://api.rn98.info/v1. Send POST requests to https://api.rn98.info/v1/audio/speech for synthesis. Use GET /v1/voices to list available voices and GET /v1/models for model details. This endpoint structure matches the standard OpenAI speech interface.
Can I use the OpenAI Python SDK?
Yes. The API uses the same request shape as the OpenAI speech endpoint. Configure your OpenAI SDK client by changing the base_url to https://api.rn98.info/v1 and providing your SpotVoce API key. This allows you to use official OpenAI SDKs without modification.
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 under load a request may wait in a queue. Long texts may take time as requests are handled one after another.
Does the API support streaming audio?
No. The API does not support streaming, WebSocket connections, or real-time partial audio. You must send the full text and wait for the complete audio file response. The response contains the generated audio file in the specified format.
How do I handle long texts?
Split your text into parts of up to 4096 characters. Send each part as a separate POST request to the speech endpoint. Once you receive the audio files for all parts, join them sequentially to create the final audio output.
What is the maximum input length?
The maximum input length is 4096 characters per request. If your text exceeds this limit, you must split it into multiple requests. Each character, including spaces and punctuation, counts toward this limit and the total character count for billing.
Is SSML supported in the input?
No. The API does not support SSML markup in the input text. You cannot use SSML tags for pronunciation, pauses, or emphasis. Input is plain text only, processed directly by the TTS engine without additional markup interpretation.
How do I specify the language?
Include the optional language field with an ISO code in the request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures correct synthesis for non-English Latin-script content.
What audio formats are available?
Available formats are mp3, wav, opus, flac, and pcm. Specify the desired format using the response_format field in your request. Each generated file carries an inaudible watermark marking it as synthetic speech, regardless of the chosen format.
Do I need to install a specific SDK?
No. You can use the official OpenAI SDKs or plain HTTP requests. There is no proprietary SpotVoce SDK. Use standard HTTP libraries or the OpenAI Python SDK by adjusting the base URL to point to our API endpoint.
Are there any required headers?
Yes. You must include the Authorization: Bearer tts-... header with your active API key. The Content-Type should be application/json. No other headers are strictly required, but ensure your key is valid and matches the account making the request.
How do I authenticate with Bearer token?
Include Authorization: Bearer tts-<your-key> in the HTTP headers of every request. Replace <your-key> with the key from your dashboard. Only one key is active per account; issuing a new key invalidates the old one immediately.
What is the response format for errors?
Failed requests return a standard error response indicating the issue. If synthesis fails, the charge is returned in full. The response includes details about the error, such as invalid parameters or rate limits, allowing you to adjust your request accordingly.
First request
curl
curl https://api.rn98.info/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.rn98.info/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.rn98.info/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
Authentication relies on a single active API key per account, issued via the /get-api-key/ dashboard. The key follows the standard Bearer token format, prefixed with 'tts-'. This single credential controls all access to the speech generation and metadata endpoints.
Bearer Token Format
Your API key is a string starting with 'tts-' followed by alphanumeric characters. It acts as the sole identifier for your account’s usage and billing. Ensure no extra whitespace surrounds the token when passing it in headers.
Key Generation and Rotation
You can generate a new key at any time from your dashboard. When a new key is issued, the previous one becomes invalid immediately. This allows for instant rotation without downtime, ensuring that only current credentials remain active.
- One active key per account
- Old key stops at once upon new issuance
- No overlapping validity period
Authorization Header
Include the key in the HTTP Authorization header for every request. The format is strict: 'Authorization: Bearer tts-...'. Incorrect formatting or missing headers will result in a 401 Unauthorized error before the request reaches the speech engine.
- Format: Authorization: Bearer <key>
- Required for all endpoints
- Case-sensitive header name
Endpoint Overview
Access the API via HTTPS. Send text for synthesis or retrieve metadata about available voices and models.
Speech Generation Endpoint
POST https://api.rn98.info/v1/audio/speech. Accepts JSON with text, voice, and format parameters. Returns an audio file.
Voices Listing Endpoint
GET https://api.rn98.info/v1/voices. Returns a list of the 8 available voice presets, supported languages, and audio formats.
Models Listing Endpoint
GET https://api.rn98.info/v1/models. Returns the available model identifiers (tts-1, tts-1-hd) and their associated metadata.
Request Parameters
Configure the synthesis request with three core parameters: model, input text, and voice. These define the engine quality, content boundaries, and acoustic style of the generated audio file.
Model Selection
Select "tts-1" for standard efficiency or "tts-1-hd" for higher fidelity. Both models use the same underlying engine and incur identical pricing, allowing you to choose based on your specific audio quality requirements without cost variance.
Input Text Length
The input field accepts up to 4096 characters per request. For longer scripts, split the text into chunks of this size and join the resulting audio files. Note that spaces and punctuation count toward this limit.
Voice Preset Selection
Choose from eight presets (e.g., aria, nova, felix, atlas) to match the tone of your spot. Each voice supports all 23 supported languages. Set the language field explicitly for non-English Latin-script text to ensure accurate synthesis.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Response Formats
Each synthesis request returns a binary audio file directly in the HTTP response body. The format is determined by your response_format parameter, allowing immediate playback or storage without post-processing conversion. The generated file includes an inaudible watermark marking it as synthetic speech.
MP3 Output
MP3 is the default format, offering a balance between file size and compatibility. It is ideal for web playback and standard video editing pipelines where minimal bandwidth usage is preferred.
WAV Output
WAV provides uncompressed, lossless audio data. This format is preferred for radio production and broadcast workflows where maximum fidelity is required before further mixing or mastering in professional DAWs.
Other Supported Formats
The API supports OPUS, FLAC, and PCM for specific technical requirements. OPUS offers high compression, FLAC provides lossless archival quality, and PCM delivers raw uncompressed data for custom processing pipelines.
- OPUS: Efficient compression for web delivery
- FLAC: Lossless archival quality
- PCM: Raw uncompressed audio data
OpenAI SDK Integration
The API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing integration logic. By adjusting the base URL, your current codebase can route requests to our infrastructure without significant refactoring.
Base URL Configuration
Set your SDK’s base_url to https://api.rn98.info/v1. This directs all standard TTS requests to our endpoint while maintaining the expected request shape.
SDK Compatibility
The official OpenAI SDKs work directly with this configuration. Since the JSON body fields (model, input, voice, response_format) match the OpenAI specification, no custom parsers are required.
Header Overrides
Provide your API key via the Authorization: Bearer tts-... header. Ensure this header is included in all requests to authenticate your agency account and track usage against your balance.

Error Handling
The API returns standard HTTP status codes to indicate request outcomes. Understanding these codes helps you implement robust error handling in your production workflows, ensuring that failed synthesis attempts do not break your automation pipelines.
400 Bad Request
This error occurs when the request body is malformed, contains invalid parameters, or exceeds the 4,096 character limit for the input field.
- Check JSON syntax and required fields.
- Ensure
inputdoes not exceed 4,096 characters. - Verify
voiceis one of the 8 valid presets.
401 Unauthorized
Returned if the Authorization: Bearer header contains an invalid, expired, or missing API key.
- Verify the key format starts with
tts-. - Check that the key is active and not revoked.
429 Rate Limit Exceeded
Triggers when you exceed 60 requests per minute (or 10 per minute initially). Failed requests are free.
- Implement exponential backoff on retry.
- Monitor the
X-RateLimit-Remainingheader.
Rate Limits
Rate limits enforce a maximum of 60 requests per minute per API key. This cap applies to all speech generation calls regardless of text length or voice preset.
Requests Per Minute
Each request counts toward the 60 requests/minute limit. Requests are processed sequentially, so high-volume batches may experience latency as they wait in the queue.
- Limit is per API key, not per IP or account.
- Both successful and failed synthesis attempts consume quota.
Initial Limit vs. Top-Up Limit
New keys start with a reduced limit of 10 requests per minute. This applies until the first top-up is processed. Upon successful USDT top-up, the limit increases to the standard 60 requests per minute automatically.
Queue Behavior
Requests are processed one after another. Under load, synthesis may wait in a queue before generation begins. This ensures consistent processing but may increase total time for large batches.
Curl Example
The API accepts standard JSON payloads, making it easy to integrate into existing ad production pipelines. Below is a minimal example for generating a 5-second spot.
You can adjust the speed or voice preset directly in the request body to match the tone of the campaign.
Basic Request Structure
Send a POST request to the speech endpoint with the text and voice parameters.
The input text is limited to 4096 characters per request.
- - Endpoint: POST https://api.rn98.info/v1/audio/speech
- - Body: JSON with model, input, voice, and response_format
Headers Configuration
Include your API key in the Authorization header.
Set the Content-Type to application/json.
- - Authorization: Bearer tts-<your-api-key>
- - Content-Type: application/json
Response Handling
On success, the API returns the audio file directly in the response body.
Ensure your client handles binary data correctly to save the audio file.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Her gentle tone reduces listener fatigue during longer audio spots.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- LibriTTS-R paper (arXiv 2305.18802)
- openai-node on GitHub
- W3C WAI: making audio and video accessible
- Creative Commons Attribution 4.0
- LibriTTS-R corpus (OpenSLR 141)
- Node.js documentation
- MDN: Web Speech API
- ISO 639 language codes
- curl documentation
- LibriVox public-domain audiobooks
- Python documentation
