Text-to-Speech API Documentation for Developers and Integrators

By FomoVoice editorial team · Updated 2026-11-18

This documentation guides developers integrating FomoVoice’s text-to-speech API into advertising workflows. Learn how to generate radio spots and voiceovers using standard HTTP requests compatible with OpenAI SDKs. We cover authentication, parameters, rate limits, and error handling with concrete examples.

Designed for freelancers and ad agencies, this guide ensures you can produce high-quality synthetic speech efficiently. You will find clear instructions on voice selection, speed adjustments, and language support, helping you scale audio production without hiring expensive voice actors.

Text-to-Speech API Documentation for Developers and Integrators

Frequently asked questions

Do I need a special SDK?

No. The API uses the same request shape as the OpenAI speech endpoint, so you can use any standard HTTP client or the official OpenAI SDKs by changing the base_url to https://api.playfomo7.com/v1. No custom SDK is required.

Can I use the OpenAI Python SDK?

Yes. The official OpenAI SDKs work by changing the base_url to https://api.playfomo7.com/v1. Use the same request shape as the OpenAI speech endpoint with your FomoVoice API key for authentication.

What is the maximum text length?

The input field supports up to 4096 characters per request. For longer texts, split the text into parts of up to 4096 characters and join the resulting audio files together.

Does the API support streaming?

No. The API does not support streaming, WebSockets, or real-time partial audio. Requests are processed synchronously, and you receive the complete audio file in the response once synthesis is finished.

Can I send SSML tags?

No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You can only send plain text input, along with voice, format, and speed parameters.

How do I set the language explicitly?

Pass the optional language field with an ISO code (e.g., 'en', 'de', 'fr'). If not set, the language is guessed from the script, defaulting to English for Latin text.

What formats are available?

You can choose from mp3, wav, opus, flac, and pcm via the response_format field. These formats cover most advertising and radio spot workflows.

Is there a rate limit per IP or per key?

Rate limits are applied per API key, not per IP. You are allowed 60 requests per minute per key, or 10 per minute before your first top-up.

How do I rotate my API key?

You can issue a new key at any time from your account page. The old key stops working immediately when the new one is active, ensuring a seamless transition.

Do I get charged for failed requests?

No. If synthesis fails, the charge is returned in full. You only pay for successful audio generation requests.

Can I generate audio in the background?

No. The API is synchronous. You send a request and wait for the audio file in the response. Requests are processed one after another, so under load, a request may wait in a queue.

Is the API synchronous or asynchronous?

The API is synchronous. You send a POST request and receive the audio file in the response. There is no webhook or background job system; you must poll or wait for the result.

Can I use the same key for multiple clients?

Yes. Each account has one active key that can be used by multiple clients or services. The rate limit of 60 requests per minute applies to the key as a whole.

What happens if I exceed the rate limit?

Requests will be queued and processed one after another. Under load, you may experience delays as requests wait in line. The limit is 60 requests per minute per key.

First request

curl

curl https://api.playfomo7.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.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playfomo7.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.playfomo7.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
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

Access the FomoVoice TTS API using a Bearer token in the Authorization header. This single key authenticates all requests from your account.

The API key is tied to your specific site account. You can generate a new key at any time via your dashboard.

Bearer Token Key

Bearer Token Key

Include your key as Authorization: Bearer tts-... in every request header. This token validates your identity and tracks usage against your rate limits and balance.

  • Format: Bearer tts-<your-key-here>
  • Case-sensitive string

Single Active Key

Single Active Key

Each account maintains one active API key at a time. If you issue a new key, the previous one becomes invalid immediately.

Key Rotation

Rotate your key anytime from the /get-api-key/ dashboard. The old key stops working instantly, ensuring secure access management for your ad agency workflows.

Endpoint Overview

Sound wave illustration for: Endpoint Overview

The FomoVoice API provides three primary endpoints for generating and managing synthetic speech. The core generation endpoint accepts text and parameters to return audio files, while the metadata endpoints list available voices and models for integration planning.

POST /v1/audio/speech

This is the main endpoint for generating audio. Send a JSON body containing the text, voice selection, and desired format to receive an audio file. It supports texts up to 4,096 characters per request, with longer texts requiring client-side splitting.

  • Accepts JSON body with model, input, voice, and response_format fields.
  • Returns audio data directly in the response.

GET /v1/voices

Retrieve the list of available voices, their associated languages, supported formats, and current pricing. This endpoint helps developers dynamically update their UI to reflect current inventory and costs without hardcoding values.

  • Returns details for all 8 voice presets.
  • Includes language support and format options per voice.

GET /v1/models

List the available synthesis models. Currently, this includes "tts-1" and "tts-1-hd", which use the same engine and pricing structure. Use this to verify model availability before sending speech requests.

Request Parameters

Sound wave illustration for: Request Parameters

Send your script text in the input field of the POST request. The API accepts up to 4096 characters per call, including spaces and punctuation. For longer radio spots or voiceovers, split your text into chunks and join the resulting audio files on your side.

Input Text Length

Each request is limited to 4,096 characters. This limit applies to the raw string sent in the input field, counting all spaces and punctuation marks. If your script exceeds this length, divide it into smaller segments and concatenate the returned audio files to create a complete spot.

Voice Selection

Choose from eight presets optimized for advertising workflows. Female voices include Aria (warm narrator), Nova (upbeat), Luna (storytelling), and Sage (instructional). Male options include Felix (energetic promo), Milo (conversational), Atlas (news), and Orion (documentary). Select the voice that matches your brand tone.

Every generated file includes an inaudible watermark identifying it as synthetic speech. This marks the file as synthetic speech.

  • 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

Response Format

Specify the audio format using the response_format parameter. Supported options are mp3, wav, opus, flac, and pcm. MP3 is recommended for web delivery due to its small file size, while WAV or FLAC offers higher quality for broadcast masters. PCM provides raw audio data for specialized processing pipelines.

Speed and Language

Sound wave illustration for: Speed and Language

Adjust playback speed between 0.25 and 4.0 to fit ad timing precisely. Slower speeds enhance clarity for complex messages, while faster rates suit quick promotions. Each adjustment affects audio length proportionally without altering voice quality or character billing.

Speed Range 0.25–4.0

Set the speed parameter to control pacing. Values below 1.0 slow down the narration; values above 1.0 accelerate it. The default is 1.0. This feature helps match voiceovers to background music beats or radio station time slots.

  • Minimum: 0.25 (half speed)
  • Maximum: 4.0 (four times speed)
  • Default: 1.0

Optional ISO Language Code

Pass the language parameter using a standard ISO 639-1 code (e.g., en, de, fr, es). This ensures correct pronunciation and intonation, especially for mixed-language content or when the default detection might misidentify the target language.

  • Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.

Default English Detection

If language is omitted, the API guesses the language from the text script. Latin script defaults to English. For non-English Latin text (like Spanish or German), always specify the language code to prevent incorrect English pronunciation.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

You can use the official OpenAI SDKs with minimal configuration. Simply update the base_url to point to our API endpoint, allowing you to leverage existing code structures without rewriting your integration logic.

The request shape is identical to the standard OpenAI speech endpoint. This means you can swap the provider in your application with just a few lines of code changes, keeping your development workflow smooth and familiar.

Change Base URL

Point your SDK’s base_url to https://api.playfomo7.com/v1. This single change directs all requests to our infrastructure while maintaining the standard OpenAI request format.

Use Official SDK

Install the standard OpenAI library as you normally would. Pass your tts-... Bearer token in the authorization header. The SDK handles serialization and response parsing exactly as it does for OpenAI’s service.

  • No custom client required
  • Standard authentication headers apply

Same Request Shape

The JSON body for POST /v1/audio/speech matches the OpenAI specification. Use parameters like model, input, voice, and response_format exactly as documented. Our API validates these fields identically to the reference implementation.

  • Supports tts-1 and tts-1-hd
  • Accepts standard audio formats
OpenAI SDK Integration

cURL Example

Sound wave illustration for: cURL Example

Use cURL to test synthesis directly from your terminal. The following command sends a short script to the API and saves the resulting audio file locally, allowing you to verify voice quality before building your automation pipeline.

Basic Request

Run this command to generate speech. Replace YOUR_API_KEY with your secret key from /get-api-key/.

  • ```bash
  • curl -X POST https://api.playfomo7.com/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Hello, this is a test spot.", "voice": "nova"}' \
  • -o output.mp3
  • ```

Headers Setup

The Authorization header must contain your Bearer token. The Content-Type must be application/json. Ensure your key starts with tts-.

Response Handling

On success, the API returns the audio file directly. Save it to a local file using the -o flag. Failed requests return JSON with an error message and no charge.

Rate Limits

Sound wave illustration for: Rate Limits

The FomoVoice API enforces strict rate limits to ensure stable synthesis performance for all users. Each API key is allowed a maximum of 60 requests per minute under normal conditions. This limit applies globally to your account, so plan your batch voiceover generation accordingly.

60 Requests Per Minute

Standard keys can process up to 60 requests per minute. This throughput allows you to generate multiple radio spot variations.

10 RPM for New Keys

New API keys start with a lower limit of 10 requests per minute. This applies until you make your first top-up. Once you add funds via USDT (TRC-20), your limit increases to the standard 60 RPM immediately.

Queue Behavior

Requests are processed sequentially. If you exceed the limit or send many requests simultaneously, additional requests will wait in a queue. You will receive the audio file once your turn arrives.

Longer texts take more time to synthesize. Keep this in mind when planning your API calls to avoid unnecessary queuing delays during peak usage times.

  • 60 RPM for verified keys
  • 10 RPM for new keys
  • Requests are processed sequentially
  • Limit increases after top-up

Error Handling

Sound wave illustration for: Error Handling

The API is designed to protect your budget by ensuring you only pay for successful synthesis. If a request fails due to server errors or invalid parameters, no charge is applied to your balance.

Failed Request Refund

Any request that does not return a valid audio file is considered failed. The system automatically reverses any attempted charge, so your character count remains unchanged. This applies to both transient network issues and permanent configuration errors.

Common Error Codes

Standard HTTP status codes indicate the issue. A 400 error means invalid input, such as text exceeding 4096 characters or an unknown voice ID. A 401 error indicates an expired or incorrect API key. A 500 error suggests a temporary server issue during synthesis.

  • 400: Bad Request (invalid format or text length)
  • 401: Unauthorized (invalid or revoked key)
  • 429: Too Many Requests (rate limit exceeded)
  • 500: Internal Server Error (synthesis failure)

Retry Logic

For 500 errors, implement a simple exponential backoff retry. Do not retry 400 errors as they will fail again. If you hit the 60 requests per minute limit, pause briefly before sending the next batch to avoid queuing delays.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence.

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. IETF RFC 7845: Ogg Opus
  3. ISO 639 language codes
  4. curl documentation
  5. Creative Commons Attribution 4.0
  6. Tether (USDT)
  7. Node.js documentation
  8. openai-python on GitHub
  9. Python documentation
  10. MDN: Web Speech API
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. OpenAI API reference: create speech

More on this site