Text-to-Speech API Documentation for Freelancers

By ReadAloud Freelance editorial team · Updated 2026-11-19

Welcome to the documentation for ReadAloud Freelance, the TTS API built for freelancers who turn text into audio for blogs, clients, and accessibility projects. This guide helps you go from zero to a working audio file in minutes, using the same request shape as the OpenAI API so you can leverage existing tools and workflows immediately.

You will find everything needed to integrate our 23-language engine into your projects: from creating your account and generating your first key to handling rate limits and errors. Whether you are using Python, JavaScript, or raw cURL, this page covers the essential endpoints, voice presets, and pricing details to help you deliver high-quality speech for your clients efficiently.

Text-to-Speech API Documentation for Freelancers

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or email. You receive one active key per account. You can issue a new key at any time, which immediately invalidates the old one. The dashboard displays your key, balance, and usage statistics for easy reference.

What is the base URL for the API?

The API base URL is https://api.ub150.net/v1. You send POST requests to https://api.ub150.net/v1/audio/speech for synthesis. Other endpoints like voices and models are available at GET /v1/voices and GET /v1/models respectively.

Can I use the OpenAI SDK?

Yes, the official OpenAI SDKs work perfectly. Simply change the base_url to https://api.ub150.net/v1 and use your site's key. The request shape matches the OpenAI speech endpoint, allowing seamless integration into your existing workflows without custom code.

How do I specify a voice?

Include the voice parameter in your JSON body. Choose from eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narrator to deep documentary, suitable for various content types.

What is the maximum input length?

The maximum input length is 4096 characters per request. For longer texts, split them into parts of up to 4096 characters and join the resulting audio files. Spaces and punctuation count toward this character limit.

How do I set the language?

Set the language parameter using an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly set it for non-English Latin-script text to ensure accuracy.

What are the available formats?

You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the response_format field in your request. These options cover most standard audio needs for blogs, accessibility projects, and client deliverables.

How does speed affect generation?

Adjust speed between 0.25 and 4.0. Typical speed is roughly real-time (25 characters per second). Short phrases take a few seconds to generate.

What happens if I exceed rate limits?

The limit is 60 requests per minute per key (10 before first top-up). Exceeding this may cause requests to wait in a queue. Failed requests are free, so you are not charged for timeouts.

Are requests processed instantly?

Requests are processed sequentially. Under load, a request may wait in a queue. Typical speed is real-time for long texts, but short phrases take a few seconds. Expect slight delays during high traffic periods.

How do I handle errors?

If synthesis fails, the charge is returned in full. Check your request format and voice availability. Use the dashboard to monitor usage and balance. Failed requests incur no cost, protecting your budget during testing.

Is the API REST-based?

Yes, it is a standard REST API. Send POST requests for speech synthesis and GET requests for voices and models. Use JSON bodies for input and receive audio files in the response. It follows standard HTTP conventions.

Can I use Bearer token auth?

Yes, use Authorization: Bearer tts-... with your API key. One active key per account is supported. Issue a new key anytime to revoke the old one immediately. This ensures secure access to your billing and generation.

How do I find model details?

Send a GET request to /v1/models to see available models. You can also choose between tts-1 and tts-1-hd models. Both use the same engine and price. The /v1/voices endpoint provides details on voices, languages, formats, and pricing.

First request

curl

curl https://api.ub150.net/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.ub150.net/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.ub150.net/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

Get Your API Key

Sound wave illustration for: Get Your API Key

To start generating audio, you need an API key. Visit the /get-api-key/ page and choose your preferred method. This key authenticates your requests to the API and tracks your character usage against your balance.

Google Sign-In

Google Sign-In

Click the Google Sign-In button to create an account instantly. This method grants you an immediate free trial credit of $0.50, allowing you to generate approximately 50,000 characters within the first seven days.

  • Instant account creation
  • $0.50 free trial credit included
  • Credits valid for 7 days

Email Sign-Up

Email Sign-Up

Enter your email and create a password to register. Accounts created this way start with a zero balance, so you will need to top up via USDT (TRC-20) before making your first request. This option is ideal if you prefer not to use Google for authentication.

  • No Google account required
  • Standard email/password authentication
  • No trial credit included

First Request

Sound wave illustration for: First Request

Start generating audio immediately with a single HTTP POST to the speech endpoint. The API accepts plain text and returns an audio file, allowing you to integrate voiceovers into client deliverables without managing infrastructure.

Curl Example

Use this command to test the endpoint. Replace YOUR_API_KEY with the key found on your dashboard and update the input text with your content.

  • curl -X POST https://api.ub150.net/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"}'

JSON Body

The request requires a JSON object containing the text, voice selection, and output format. You can optionally specify a speed between 0.25 and 4.0 or lock the language ISO code.

SDK Integration

Sound wave illustration for: SDK Integration

Integrate ReadAloud Freelance into your workflow using the OpenAI SDK, which is already familiar to most developers. The only adjustment required is pointing the client to our API base URL instead of OpenAI’s servers. This allows you to reuse existing code snippets and libraries without learning a new client structure.

Once configured, your scripts can generate speech in any of the 23 supported languages instantly.

OpenAI SDK

The TTS endpoint follows the same request shape as OpenAI’s speech API. You can use any standard OpenAI SDK version with the tts-1 or tts-1-hd models. Simply pass your text, voice, and format parameters as usual.

  • Use standard openai Python or Node.js packages
  • Supports tts-1 and tts-1-hd models
  • Identical JSON body structure to OpenAI

Base URL Change

To direct requests to ReadAloud Freelance, update your SDK’s base URL configuration. Set the base URL to https://api.ub150.net/v1 and use your unique API key for authentication.

This single change routes all synthesis requests to our infrastructure while maintaining standard headers and response formats. Your existing rate-limiting and error-handling logic will continue to work as expected.

  • Base URL: https://api.ub150.net/v1
  • Auth: Authorization: Bearer tts-...
  • No other code changes needed

Voices Endpoint

Sound wave illustration for: Voices Endpoint

Fetch available voices and supported languages with a simple GET request to /v1/voices. This endpoint returns the full list of 8 presets, their audio characteristics, and the 23 supported languages, helping you choose the right voice for your client's content without guessing.

List Voices

Use GET /v1/voices to retrieve details for all 8 voice presets, including Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. Each voice has distinct tonal qualities suitable for blogs, tutorials, or documentaries. The response confirms available formats and pricing, ensuring you select the optimal model before generation.

  • GET https://api.ub150.net/v1/voices
  • Returns JSON array of voice objects
  • Includes voice ID, name, and gender

Language Codes

Pass the language parameter as an ISO 639-1 code (e.g., en, de, fr) to ensure accurate pronunciation. While the API guesses language from the script, explicitly setting it prevents errors for Latin-script texts that aren't English. Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.

  • en: English
  • de: German
  • fr: French
  • es: Spanish
  • ja: Japanese
  • zh: Chinese

Models

Sound wave illustration for: Models

The API offers two model options, tts-1 and tts-1-hd, which use the same underlying engine and share identical pricing. You can choose either without affecting your cost per character.

Both models support the full range of 8 voice presets and 23 languages, ensuring consistent quality regardless of your selection.

tts-1

This is the standard model for general text-to-speech generation. It delivers audio suitable for blog posts, audiobooks, and accessibility content.

  • Standard quality output
  • $0.01 per 1,000 characters
  • Same engine as tts-1-hd

tts-1-hd

The high-definition variant provides audio fidelity. It is ideal for projects where sound quality is a priority, such as professional client deliverables or high-end podcasts.

  • High-definition audio quality
  • $0.01 per 1,000 characters
  • Same engine as tts-1
Models

Request Parameters

Sound wave illustration for: Request Parameters

Freelancers often need to convert blog posts or client copy into audio quickly. This API handles the heavy lifting, letting you focus on content strategy rather than infrastructure management.

Input Text

Send your script via the input field. You can send up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer articles, split the text and join the resulting audio files.

  • Max 4096 characters per request
  • Spaces and punctuation count as characters
  • Split and join for longer content

Speed Control

Adjust the speed parameter to fit your project's tone. Valid values range from 0.25 to 4.0. Use slower speeds for instructional content and faster rates for quick summaries or energetic promos.

  • Range: 0.25–4.0
  • Adjustable per request
  • No SSML or phoneme tags

Response Format

Sound wave illustration for: Response Format

Successful synthesis returns the generated audio file directly in the response body. The format matches your response_format choice—mp3, wav, opus, flac, or pcm—allowing immediate playback or saving to your client’s project folder. Since requests are processed sequentially, longer texts may experience slight delays as they queue behind other users’ requests.

If synthesis fails, the API returns a standard error JSON with a code and message. Crucially, any failed request is completely free, so you will not be charged for characters that did not result in audio. This protects your budget when dealing with edge cases or network hiccups.

Audio File

The response body contains the raw audio bytes. Save this directly to disk or stream it to your audio player. Remember that input text is limited to 4096 characters per request; for longer scripts, split the text, generate each part, and join the resulting audio files.

Generated audio is not stored on our servers after the response is sent, ensuring your client’s content remains yours. Each file carries an inaudible watermark marking it as synthetic speech.

  • Supported formats: mp3, wav, opus, flac, pcm
  • Max input: 4096 characters per request
  • Audio is returned in the response body, not stored

Error Codes

Errors return a JSON object with an error code and descriptive message. Common issues include invalid API keys, unsupported voices, or text exceeding the character limit.

Most importantly, failed requests are free. If synthesis fails, the charge is returned in full, so you can retry or debug without worrying about your balance. This makes testing your freelancer workflows risk-free.

  • Failed requests are free
  • Returns JSON with error code and message
  • No hidden charges for failed synthesis

Rate Limits

Sound wave illustration for: Rate Limits

Your API key allows 60 requests per minute, but starts at a conservative 10 requests per minute until you add your first top-up. This limit ensures fair usage across our shared infrastructure while you manage multiple client projects.

60 Requests Per Minute

Once you top up your USDT balance, your limit increases to 60 requests per minute. This tier supports high-volume freelance workflows, such as generating audio for long blog posts or accessibility documents without hitting walls.

  • Starts at 10 req/min for new accounts
  • Increases to 60 req/min after first top-up
  • Limits apply per API key, not per project

Queue Handling

Requests are processed sequentially, meaning under heavy load, your synthesis job may wait in a queue. Short phrases typically generate in a few seconds, while longer texts process at roughly real-time speed (25 characters per second).

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. For content creators working with diverse audiences, language support is critical.

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

More on this site