Developer Guide: Integrate Automatic Voice Over

By RK66 Editorial Team · Updated 2026-11-19

This guide helps development teams integrate automatic voice-over for accessible video content. You will learn how to connect your application to the VoxEase API, configure audio generation for dyslexic and neurodivergent audiences, and manage keys securely. The documentation covers authentication, endpoints, and code examples for Python and JavaScript, ensuring you can generate clear, compliant audio files efficiently.

Readers will find specific instructions on parameter selection, rate limits, and error handling. We detail how to use the OpenAI-compatible SDKs, adjust voice speed, and select languages for 23 supported tongues. This page provides the technical steps needed to build a reliable TTS pipeline, focusing on practical integration details without unnecessary complexity or hype.

Developer Guide: Integrate Automatic Voice Over

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.rk66.info/v1. You can use this endpoint to send POST requests for audio synthesis or GET requests to retrieve voice and model information. This URL serves as the foundation for all interactions with the VoxEase text-to-speech service.

How do I authenticate my requests?

Include your API key in the Authorization header using the Bearer scheme. The format is Authorization: Bearer tts-.... Each account has one active key, and issuing a new key immediately invalidates the previous one. Ensure your key is valid before sending requests.

Which models are available?

Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing. You can select either model in your request body. The choice does not affect the cost, which remains $10 per million characters regardless of the model selected.

What is the difference between tts-1 and tts-1-hd?

There is no functional difference in price or engine between tts-1 and tts-1-hd. Both models produce audio with the same characteristics and cost $10 per million characters. You may use either model identifier interchangeably in your API requests without affecting the billing rate.

Can I change the speed of the audio?

Yes, you can adjust the speed using the speed parameter. Valid values range from 0.25 to 4.0. Setting a higher value increases playback speed, while a lower value slows it down. This allows you to tailor the audio pace to your specific content needs.

How do I specify the language?

Pass the ISO code in the language field. If omitted, the system guesses the language, defaulting to English for Latin script. For non-English Latin text, explicitly set the language to ensure accurate synthesis. Supported languages include English, Spanish, French, German, and others listed in the voices endpoint.

What formats are supported?

You can request audio in mp3, wav, opus, flac, or pcm formats. Specify your preferred format using the response_format parameter in the request body. The API returns the generated audio file in the selected format, allowing flexibility for different playback environments and storage requirements.

How many characters can I send?

Each request supports up to 4096 characters in the input field. This limit applies per API call. If your text exceeds this length, you must split it into smaller chunks. Each chunk is processed separately, and the resulting audio files are joined to form the final output.

What happens if I exceed the rate limit?

The rate limit is 60 requests per minute per key. Before the first top-up, the limit is 10 requests per minute. If you exceed this, requests may be queued or rejected. Requests are processed sequentially, so high volume may cause delays in audio generation.

Do I need to split long texts manually?

Yes, you must split texts longer than 4096 characters yourself. The API does not handle automatic splitting. You should divide the text into parts, send each part in a separate request, and then join the resulting audio files to create the complete voice-over.

Is the API compatible with OpenAI SDK?

Yes, the request shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.rk66.info/v1 and providing your VoxEase API key. This allows you to leverage existing SDK functionality with minimal code changes.

How do I handle audio responses?

The API returns the audio file directly in the response body. You can save this data to a file. The response format depends on the response_format parameter you specified. Failed requests return no audio and do not charge your balance.

What is the character limit per request?

The character limit is 4096 characters per request. This includes spaces and punctuation. If your input exceeds this limit, the API will reject the request. Ensure you split longer texts into segments of 4096 characters or less before sending them to the endpoint.

Are there limits on audio length?

There is no explicit limit on the total audio length, as you can concatenate multiple requests. However, each request is limited to 4096 characters. Processing time depends on text length, with typical speeds of roughly 25 characters per second. Longer texts may take more time due to queuing.

First request

curl

curl https://api.rk66.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.rk66.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.rk66.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 and Keys

Sound wave illustration for: Authentication and Keys

VoxEase uses standard Bearer token authentication. Include your API key in the request header as Authorization: Bearer tts-<your-key>. This single key authenticates all requests to the speech endpoint.

Bearer Token Format

Bearer Token Format

The token must be sent exactly as shown. Ensure there are no extra spaces or quotes around the key value. The system validates this header for every request.

Single Active Key Policy

Single Active Key Policy

Each account maintains only one active API key at any time. If you generate a new key, the previous one becomes invalid immediately. This ensures consistent access control for your team.

  • One key per account
  • New key invalidates old key instantly

Instant Key Revocation

Revocation happens immediately upon key generation. There is no delay or grace period. You can issue a new key at any time via your dashboard to reset access.

Base URL and Endpoint

Sound wave illustration for: Base URL and Endpoint

All API requests target the base URL https://api.rk66.info/v1. This structure ensures compatibility with standard HTTP clients and allows teams to integrate the automatic voice-over service directly into their existing accessibility workflows without custom infrastructure.

The primary endpoint generates audio from text, while dedicated endpoints provide metadata about available voices and model configurations. This separation simplifies debugging and ensures that your team can verify supported formats before submitting large batches of text for processing.

Speech Endpoint Path

Send a POST request to /v1/audio/speech to receive an audio file. The JSON body follows the standard shape used by major SDKs, making it easy to swap in your preferred library.

The service accepts text up to 4096 characters per request. For longer scripts, split the input and join the resulting audio files to maintain consistent quality and predictable processing times.

  • Method: POST
  • Path: /v1/audio/speech
  • Content-Type: application/json

GET /v1/voices Endpoint

Use this endpoint to retrieve the list of eight voice presets, supported languages, and available audio formats. It provides the exact data needed to configure your synthesis requests correctly.

The response includes metadata on pricing and language support, helping teams select the most appropriate voice for their specific audience without guessing parameters.

GET /v1/models Endpoint

This endpoint returns the available model identifiers, specifically tts-1 and tts-1-hd. Both models use the same engine and pricing structure, offering flexibility based on your quality requirements.

Refer to this endpoint to confirm model availability and ensure your integration remains compatible with the latest infrastructure updates.

Required Parameters

Sound wave illustration for: Required Parameters

Configure the core request parameters to generate audio that fits your accessibility workflow. Each parameter ensures the synthetic voice output meets your team’s specific content standards.

Model Selection (tts-1 / tts-1/hd)

Select either tts-1 or tts-1-hd. Both models use the same underlying engine and incur identical pricing, allowing you to switch formats without cost implications.

Input Text Field

Provide your script content in the input field. The API accepts up to 4,096 characters per request. For longer scripts, split the text into parts and join the resulting audio files.

  • Spaces and punctuation count toward the character limit.

Voice Selection

Choose one of the eight preset voices to match your content tone. Each voice is distinct, ranging from clear narrators to deep documentary styles, ensuring consistent audibility for neurodivergent audiences.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion

Optional Parameters

Sound wave illustration for: Optional Parameters

Optional parameters allow you to fine-tune the output without changing the core synthesis engine. These settings help adapt the generated audio to specific accessibility needs or technical requirements for your video content workflows.

Speed Adjustment (0.25–4.0)

Adjust speech rate from 0.25x to 4.0x to match listener preferences. Slower speeds aid comprehension for neurodivergent audiences, while faster rates suit quick updates.

  • Default speed is 1.0
  • Supports fractional values for precise control

Language ISO Code

Specify an ISO language code to override automatic detection. This ensures correct pronunciation when the input text uses Latin script but is not English, preventing default English voice assignment.

  • Supported: 23 languages including English, Spanish, German, Arabic, and Japanese
  • Not supported: Vietnamese, Thai, Ukrainian, Romanian, Czech, Bengali

Response Format Selection

Choose between mp3, wav, opus, flac, or pcm formats. MP3 offers balanced quality and file size, while WAV provides uncompressed audio. OPUS and FLAC offer efficient compression for long videos.

  • mp3: Standard compressed audio
  • wav: Uncompressed, high fidelity
  • opus: Efficient compression
  • flac: Lossless compression
  • pcm: Raw audio data

Example: cURL Command

Sound wave illustration for: Example: cURL Command

The API accepts text input up to 4096 characters, counting spaces and punctuation toward the character limit. Each request returns a single audio file in the specified format. For longer voice-over scripts, split the text into chunks and join the resulting files.

The following cURL examples demonstrate how to request audio in MP3, WAV, and OPUS formats. Replace YOUR_API_KEY with your active Bearer token from the dashboard.

Basic MP3 Request

This command generates a standard MP3 file, suitable for most web and video players. The response returns the audio binary data directly to your terminal or file output.

  • Model: tts-1
  • Format: mp3
  • Max characters: 4096

WAV Format Request

Use this endpoint for uncompressed audio needs, such as high-quality video editing timelines. The WAV file is larger but ensures no lossy compression artifacts during editing.

  • Model: tts-1
  • Format: wav

OPUS Format Request

OPUS provides efficient compression for storage-constrained environments. This format is ideal for distributing voice-over content where bandwidth efficiency matters.

  • Model: tts-1
  • Format: opus
Example: cURL Command

Example: OpenAI SDK Integration

Sound wave illustration for: Example: OpenAI SDK Integration

The API mirrors the OpenAI speech endpoint shape, allowing you to reuse existing SDKs by simply pointing the base URL to https://api.rk66.info/v1. This ensures your team can integrate automatic voice-over into accessible video workflows without learning a new library structure.

Base URL Configuration

Set the base URL to https://api.rk66.info/v1. Use your Bearer token from the dashboard for authentication. This works with the official OpenAI SDKs, enabling direct replacement of the default endpoint.

Python SDK Snippet

Install the openai package. Configure the client with your API key and the custom base URL. Call the audio.speech method with your text, voice, and model parameters.

  • client = OpenAI(base_url="https://api.rk66.info/v1", api_key="tts-...")
  • audio_stream = client.audio.speech.create(model="tts-1", voice="aria", input="Text")

JavaScript SDK Snippet

Initialize the OpenAI client with the API key and base URL. Invoke the audio.speech.create method to generate the audio file. Handle the response to save the MP3 or WAV output.

  • const client = new OpenAI({ baseURL: 'https://api.rk66.info/v1', apiKey: 'tts-...' });
  • const response = await client.audio.speech.create({ model: 'tts-1', voice: 'nova', input: 'Text' });

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

VoxEase enforces a strict rate limit of 60 requests per minute per API key to ensure stable generation for your accessibility workflows. This limit applies to all voice synthesis calls, regardless of text length or format.

60 Requests Per Minute

Each active key allows up to 60 synthesis requests within a sliding 60-second window. Exceeding this threshold triggers a 429 error, pausing your batch jobs until the window resets.

10 Requests Before Top-Up

New accounts starting with the free trial credit are limited to 10 requests per minute. Once you top up via USDT (TRC-20), this restriction lifts to the standard 60 requests per minute.

Queue Behavior Under Load

Requests are processed sequentially. Under heavy load, your synthesis job may wait in a queue before generation begins. This ensures audio integrity but may increase total processing time for large batches.

Error Handling and Codes

Sound wave illustration for: Error Handling and Codes

API responses include standard HTTP status codes to indicate success or failure. Understanding these codes helps you handle errors gracefully in your video production workflow.

400 Bad Request Examples

Return 400 when the request body is invalid. Common causes include an input field exceeding 4096 characters or an unsupported voice ID. Ensure all JSON fields are correctly formatted.

  • Text exceeds 4096 character limit
  • Invalid voice identifier
  • Malformed JSON structure

429 Rate Limit Exceeded

Requests return 429 when you exceed 60 requests per minute. New accounts start with a limit of 10 requests per minute until the first top-up is processed.

  • Standard limit: 60 req/min
  • Initial limit: 10 req/min
  • Check Retry-After header

500 Server Error Cases

A 500 error indicates a server-side issue during synthesis. These are rare, but if they occur, the charge is returned in full. Retry the request after a short delay.

  • Synthesis engine failure

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This combination supports better retention of information in video content.

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. TRON developer hub: TRC-20
  3. W3C WAI: making audio and video accessible
  4. Python documentation
  5. ISO 639 language codes
  6. openai-python on GitHub
  7. LibriVox public-domain audiobooks
  8. Node.js documentation
  9. LibriTTS-R corpus (OpenSLR 141)
  10. Tether (USDT)
  11. OpenAI API reference: create speech
  12. MDN: Web Speech API

More on this site