Complete Guide to the Text-to-Speech API Integration

By CivicVoice editorial team · Updated 2026-11-18

This documentation provides a complete reference for integrating CivicVoice’s text-to-speech API into your applications. We outline the essential endpoints, authentication methods, and parameter configurations needed to convert plain text into clear audio files for multilingual communities.

Designed for indie developers and technical teams, this guide covers quickstart examples using cURL and the OpenAI SDK. You will find detailed references for voice selection, audio formats, rate limits, and error handling to ensure reliable integration without complex infrastructure.

Complete Guide to the Text-to-Speech API Integration

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or an email and password. Accounts are specific to this site. Once registered, you can view your active API key, balance, and usage details directly on the dashboard page.

What is the base URL?

The API base URL is https://api.playfb7.com/v1. You use this endpoint for all requests, including POST /v1/audio/speech for synthesis, GET /v1/voices for available options, and GET /v1/models for model information. Ensure your client library points to this specific domain.

How do I use the OpenAI SDK?

The official OpenAI SDKs work by changing the base_url to https://api.playfb7.com/v1. Use your CivicVoice API key for authentication. The request shape matches the OpenAI speech endpoint, allowing you to generate audio files using the same code structure you would use for OpenAI's TTS service.

What parameters are required?

You must provide the model ("tts-1" or "tts-1-hd"), input text (up to 4096 characters), and voice (one of eight presets). Optional parameters include response_format, speed (0.25–4.0), and language. The language defaults to English if not set and the script is Latin.

What is the character limit?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer texts, split the content into parts of 4096 characters or less, generate audio for each part, and join the resulting audio files.

What audio formats are supported?

Supported formats are mp3, wav, opus, flac, and pcm. You specify the desired format using the response_format parameter in your request. The API returns the generated audio file in the specified format directly in the response body.

What is the rate limit?

The limit is 60 requests per minute per API key. New accounts start with a lower limit of 10 requests per minute until the first top-up is processed. Requests are processed sequentially, so high load may cause queuing delays.

How do I handle errors?

If synthesis fails, the charge is returned in full. Monitor your response status codes to detect failures. Failed requests do not consume your character balance. Ensure your input text is within the 4096 character limit and the voice ID is valid.

Can I change the speed?

Yes. Use the speed parameter with values between 0.25 and 4.0 to adjust playback rate. This allows you to slow down narration for clarity or speed up content for efficiency. You can explicitly set the value to suit your specific audio requirements.

Is the API compatible with OpenAI?

Yes. The API accepts the same JSON request shape as OpenAI, so the official OpenAI SDKs work by changing the base_url to https://api.playfb7.com/v1. The models tts-1 and tts-1-hd use our engine, but the request structure remains identical. We are not affiliated with OpenAI.

How do I rotate my API key?

You can issue a new API key at any time from your account dashboard. When a new key is generated, the old one stops working immediately. This ensures secure access management without needing to wait for manual approval or expiration.

What happens if I exceed the limit?

If you exceed 60 requests per minute, subsequent requests may queue or fail. New accounts have a 10 requests per minute limit until the first top-up is credited. Failed requests are free, so exceeding limits does not incur extra charges; it only affects processing speed or results in a free failure.

Can I use multiple voices?

Yes, you can choose from eight voice presets: aria, nova, luna, sage, felix, milo, atlas, and orion. Each voice can speak any of the 23 supported languages. You specify the voice in each request to vary the audio output.

Is there a limit on request size?

The input text is limited to 4096 characters per request. This includes all spaces and punctuation. For longer content, you must split the text into smaller chunks, generate audio for each chunk, and then concatenate the resulting audio files.

First request

curl

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

Accessing the CivicVoice API requires a valid authentication key, which is issued upon account creation via /get-api-key/. Each account maintains a single active key, ensuring straightforward credential management for government and NGO developers integrating audio synthesis into their digital services.

The key is transmitted as a Bearer token in the Authorization header of every request. This standard approach ensures compatibility with existing HTTP clients and the official OpenAI SDKs, allowing teams to switch base URLs without modifying their core authentication logic.

API Key Management

Keys are generated on the /get-api-key/ dashboard page alongside your current balance and usage statistics. You can revoke and issue a new key at any time from this same interface, immediately invalidating the previous token.

  • One active key per account
  • Issued via /get-api-key/ dashboard
  • Immediate invalidation upon rotation

Bearer Token Usage

Include your key in the header: Authorization: Bearer tts-.... This format works seamlessly with both plain HTTP requests and the OpenAI Python/Node SDKs when the base_url is adjusted to https://api.playfb7.com/v1.

The token grants access to all endpoints, including speech synthesis and voice listing. Ensure the key is kept secure in your deployment environment variables rather than hardcoding it in client-side code.

  • Header: Authorization: Bearer <key>
  • Compatible with OpenAI SDKs
  • Supports standard HTTP clients

Key Rotation

Rotating your key is instant. Generate a new key on the dashboard, and the old one stops working immediately. This allows you to update credentials in your infrastructure without a service interruption, provided you switch the token before the old one expires or is revoked.

There is no downtime during rotation. Update your application configuration to use the new key, and subsequent requests will succeed while older requests using the old key will return a 401 Unauthorized error.

  • Instant invalidation of old key
  • Zero downtime if configured correctly
  • No manual approval required

Endpoint Overview

Sound wave illustration for: Endpoint Overview

The API exposes three primary endpoints for generating and managing audio. The Speech endpoint accepts text and returns audio files, while the Voices and Models endpoints provide metadata for configuration. This structure allows developers to integrate CivicVoice into existing workflows with minimal overhead.

Each endpoint serves a distinct purpose in the synthesis pipeline. Developers use the Voices and Models endpoints to verify available parameters before sending requests to the Speech endpoint. This separation ensures that applications can adapt to changes in voice availability or model updates without disrupting the core audio generation process.

Speech Endpoint

Send a POST request to /v1/audio/speech with your text and desired parameters. The API processes requests sequentially, so under load, synthesis may queue briefly before returning. The response contains the generated audio file in the requested format.

Failed requests are free, with charges returned in full if synthesis fails. The input text is limited to 4096 characters per request. For longer texts, split the input and join the resulting audio files.

  • Endpoint: POST /v1/audio/speech
  • Returns: Audio file (mp3, wav, opus, flac, pcm)
  • Limit: 4096 characters per request

Voices Endpoint

The GET /v1/voices endpoint returns a list of available voice presets, supported languages, and audio formats. This allows your application to dynamically populate user interfaces with valid options. You can verify that the selected voice supports the desired language before making a speech request.

  • Endpoint: GET /v1/voices
  • Returns: Voice presets, languages, formats
  • Use: Validate options before synthesis

Models Endpoint

The GET /v1/models endpoint lists available models, such as tts-1 and tts-1-hd. Both models use the same engine and pricing. Use this endpoint to confirm model availability and ensure your application requests a valid model identifier.

  • Endpoint: GET /v1/models
  • Returns: Available model identifiers
  • Use: Confirm valid model names
Endpoint Overview

Quickstart with cURL

Sound wave illustration for: Quickstart with cURL

CivicVoice’s API accepts text input and returns synthesized audio via a simple POST request. This quickstart demonstrates the essential cURL command, covering the required JSON body, authentication header, and expected response structure for immediate integration testing.

Request Structure

Send a POST request to https://api.playfb7.com/v1/audio/speech. The body must include the model ("tts-1" or "tts-1-hd"), the input text (max 4096 characters), and a voice preset. Include your API key in the Authorization header as a Bearer token.

  • Endpoint: POST /v1/audio/speech
  • Auth: Authorization: Bearer tts-...
  • Body: model, input, voice, response_format, speed

Response Format

Successful requests return the audio file directly in the response body, with the content type matching your requested response_format (e.g., audio/mpeg for MP3). No additional JSON wrapper is included, allowing direct file saving or streaming into audio players.

Error Handling

If synthesis fails, the API returns an error status code. Crucially, failed requests incur no charge, and any pre-paid balance remains intact. Check the response body for details on why the request failed, such as invalid character limits or unsupported voices.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

Integrating CivicVoice with existing codebases is straightforward because the API follows the same request structure as the OpenAI Speech endpoint. By simply adjusting the base URL, developers can leverage standard OpenAI SDKs without learning a new library or format.

This approach allows government and NGO teams to maintain their current development workflows while accessing multilingual TTS capabilities for accessibility projects.

Base URL Configuration

Set the SDK base URL to https://api.playfb7.com/v1. This directs all standard speech requests to the CivicVoice infrastructure. Ensure your API key is valid for this specific site domain.

Client Initialization

Initialize the OpenAI client using your standard language SDK. Pass the base URL and your tts-... Bearer token via the Authorization header. The SDK handles JSON serialization automatically.

Request Examples

Use the standard AudioResponse model or plain HTTP POST to https://api.playfb7.com/v1/audio/speech. Send a JSON body with model, input, voice, and response_format. The SDK returns the audio file directly for playback or storage.

Parameters Reference

Sound wave illustration for: Parameters Reference

The API accepts two model identifiers, "tts-1" and "tts-1-hd," which utilize the identical underlying engine and carry the same price per character. Selecting one over the other does not alter the base processing cost or the fundamental audio source, though the "hd" label may imply a different file encoding context for clients expecting high-definition metadata.

Model Selection

Choose "tts-1" or "tts-1-hd" based on your client's existing configuration expectations. Both parameters trigger the same synthesis engine, ensuring consistent voice characteristics regardless of the identifier used. The pricing remains uniform at $0.01 per 1,000 characters, so the choice is primarily about API contract alignment rather than cost or engine difference.

Voice Selection

Select from eight preset voices, each designed for specific tonal needs. Female voices include Aria (warm narrator), Nova (upbeat), Luna (storytelling), and Sage (instructional). Male options include Felix (energetic), Milo (conversational), Atlas (neutral news), and Orion (documentary). Any voice supports all 23 languages; set the language code explicitly for non-English Latin text to ensure accurate pronunciation.

  • Aria: Warm, clear narrator
  • Nova: Bright, upbeat
  • Luna: Soft, storytelling
  • Sage: Calm, instructional
  • Felix: Energetic, promo
  • Milo: Friendly, conversational

Speed Control

Adjust playback speed between 0.25 and 4.0 using the speed parameter. This allows fine-tuning of audio duration without re-synthesizing the text. Note that synthesis itself is not real-time; longer texts are split into 4,096-character chunks and processed sequentially, so speed adjustments apply to the final output file rather than the generation queue latency.

Parameters Reference

Audio Formats

Sound wave illustration for: Audio Formats

CivicVoice allows you to select the audio container that best fits your infrastructure. You can request MP3, WAV, OPUS, FLAC, or PCM formats by passing the response_format parameter in your JSON body. The API returns the synthesized audio file in the specified format, ensuring compatibility with your existing playback systems.

MP3 Support

MP3 is the most widely supported format for web players and mobile applications. It provides a balance between file size and audio quality, making it suitable for general distribution to multilingual communities.

WAV Support

WAV files are generated without additional compression layers. This format is ideal for local storage or processing pipelines that require raw audio data without decoding overhead.

OPUS and FLAC Support

OPUS offers high efficiency with good quality, often preferred for voice communication streams. FLAC provides lossless compression, ensuring the audio remains identical to the source while reducing storage requirements compared to WAV.

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

CivicVoice enforces strict rate limits to ensure stable synthesis performance. Each API key is permitted 60 requests per minute once funded, with a lower baseline of 10 requests per minute for new accounts prior to the first top-up. These quotas reset on a sliding window basis.

Requests Per Minute

New accounts without a top-up are limited to 10 requests per minute. After your first USDT transfer is credited to your balance, the limit increases to 60 requests per minute. This higher limit applies to your active key as soon as the credit appears in your account, not instantly upon sending the transfer.

Character Limits

Each request can process up to 4096 characters. Spaces and punctuation count toward this limit. For texts exceeding this threshold, you must split the input into multiple requests and join the resulting audio files.

Queue Behavior

Requests are processed sequentially. During periods of high load, your request may wait in a queue before synthesis begins. Short phrases typically take a few seconds to generate, while longer texts process at roughly real-time speed (25 characters per second).

Rate Limits and Quotas

Error Codes

Sound wave illustration for: Error Codes

Understanding error responses ensures your integration handles failures gracefully without unnecessary retries. CivicVoice returns standard HTTP status codes to indicate the nature of the issue, allowing developers to adjust request parameters or authentication headers accordingly.

400 Bad Request

This error indicates a problem with the request structure or content. Common causes include missing required fields, invalid voice IDs, or text exceeding the 4,096-character limit per request. Review the JSON payload to ensure all parameters match the expected schema.

  • Ensure input does not exceed 4,096 characters.
  • Verify voice matches one of the 8 available presets.
  • Check that model is either tts-1 or tts-1-hd.

401 Unauthorized

A 401 error occurs when the API key is missing, incorrect, or invalid. Ensure your Authorization: Bearer tts-... header is present and matches the key issued in your dashboard. If you rotated your key, the old one stops immediately.

429 Too Many Requests

This response signifies that you have exceeded the rate limit of 60 requests per minute per key. During high-volume usage, requests are processed sequentially, so exceeding limits may result in queuing delays before the error appears. Wait before retrying.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Simplify grant applications to empower indie developers navigating complex government and NGO funding landscapes effectively.

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. OpenAI API reference: create speech
  3. curl documentation
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. Python documentation
  6. FFmpeg documentation
  7. ISO 639 language codes
  8. Tether (USDT)
  9. W3C WAI: making audio and video accessible
  10. openai-node on GitHub
  11. Creative Commons Attribution 4.0
  12. MDN: Web Speech API

More on this site