Integrate Our Cloud TTS API for Text-to-Speech

By Rn98 editorial team · Updated 2026-11-19

This guide details the integration of SpotVoce’s cloud Text-to-Speech API, designed specifically for advertising agencies and radio production teams. It covers the technical requirements for generating audio spots programmatically, ensuring your creative workflows remain automated and reliable without manual hand-offs.

You will find the exact endpoint structures, authentication methods, and OpenAI SDK compatibility details needed to generate voice-overs efficiently. The documentation provides concrete examples for handling text input, selecting voice presets, and managing rate limits within your existing production pipelines.

Integrate Our Cloud TTS API for Text-to-Speech

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.mp3

Python (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
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication

Sound wave illustration for: 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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

OpenAI SDK Integration

Error Handling

Sound wave illustration for: 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 input does not exceed 4,096 characters.
  • Verify voice is 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-Remaining header.

Rate Limits

Sound wave illustration for: 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

Sound wave illustration for: 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.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. LibriTTS-R paper (arXiv 2305.18802)
  3. openai-node on GitHub
  4. W3C WAI: making audio and video accessible
  5. Creative Commons Attribution 4.0
  6. LibriTTS-R corpus (OpenSLR 141)
  7. Node.js documentation
  8. MDN: Web Speech API
  9. ISO 639 language codes
  10. curl documentation
  11. LibriVox public-domain audiobooks
  12. Python documentation

More on this site