API Documentation: Generate Audio with Text

By CivicSonic Editorial Team · Updated 2026-11-19

This guide helps NGOs and public service teams integrate CivicSonic’s text-to-speech API into their workflows. You will learn how to convert written content into clear audio files using simple HTTP requests. The documentation covers authentication, endpoints, and parameters, ensuring you can generate speech in 23 languages, including Hindi, for diverse audiences.

We provide concrete examples using cURL and the official OpenAI SDK to demonstrate quick integration. You will find details on character-based pricing, rate limits, and handling long texts. This page is designed for product teams who need a reliable, infrastructure-light solution for converting text to audio without complex setup.

API Documentation: Generate Audio with Text

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.ex66.info/v1. You send POST requests to https://api.ex66.info/v1/audio/speech for speech synthesis. Other endpoints like /v1/voices and /v1/models are also available under this base URL structure for retrieving voice options and model details.

How do I set the language to Hindi?

Include the language parameter set to the ISO code for Hindi in your request body. Although voices can speak any of the 23 supported languages, explicitly setting the language ensures correct pronunciation. Hindi is fully supported alongside other languages like English and French.

Can I use the OpenAI Python SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.ex66.info/v1. You use the site's key with the same request shape as the OpenAI speech endpoint. This allows you to integrate CivicSonic into existing Python workflows without rewriting client code.

What happens if I exceed the rate limit?

The rate limit is 60 requests per minute per key. If you exceed this, requests may be queued or rejected. New accounts start with 10 requests per minute until the first top-up. Failed requests are free, but successful ones consume your character balance.

Does the API support SSML tags?

No, the API does not support SSML tags. It accepts plain text input up to 4096 characters. You cannot use SSML for fine-grained control over pronunciation or pacing. For custom timing, you can adjust the speed parameter between 0.25 and 4.0.

How do I handle errors in the response?

If synthesis fails, the charge is returned in full. You should check the HTTP status code and response body for error details. Failed requests do not consume your character balance, ensuring you are not billed for unsuccessful audio generation attempts.

Is the API compatible with JavaScript?

Yes, you can use plain HTTP requests or the OpenAI JavaScript SDK by setting the base URL to https://api.ex66.info/v1. The API accepts JSON bodies and returns audio files, making it compatible with standard web development practices in any JavaScript environment.

Can I stream the audio as it generates?

No, the API does not support streaming or WebSocket connections. You send a request and receive the complete audio file in the response. For longer texts, you must split the input into parts, generate each, and join the resulting audio files.

What is the maximum input length?

The maximum input length is 4096 characters per request. For longer texts, you should split the content into chunks of up to 4096 characters. Generate audio for each chunk and then join the audio files to create the final output.

How do I verify my API key?

Include your API key in the Authorization header as 'Bearer tts-...'. You can view your active key on the /get-api-key/ page. If needed, you can issue a new key, which immediately invalidates the old one. Only one key is active per account.

Does the API return metadata with audio?

The API returns the audio file directly in the response. Request metadata like time, characters, and status are kept for billing purposes but are not included in the audio response. Generated audio is not stored; it is returned immediately upon completion.

Can I request audio in FLAC format?

Yes, you can specify FLAC as the response_format in your request. Other supported formats include mp3, wav, opus, flac, and pcm. The choice of format does not affect the price, which is based on characters processed.

How do I regenerate my API key?

You can issue a new API key from the /get-api-key/ page. When a new key is issued, the old one stops working immediately. This allows you to rotate keys for security without downtime, as only one key is active per account at a time.

Is there a webhook for completion?

No, there is no webhook for completion. The API is synchronous; you send a request and wait for the audio file in the response. For long texts, you handle splitting and joining on your side, as the API does not push notifications.

First request

curl

curl https://api.ex66.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.ex66.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.ex66.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 is handled via a Bearer token passed in the HTTP header. This single key controls access to your account’s character quota and usage limits.

Bearer token format

Bearer token format

Include your key in every request header as Authorization: Bearer tts-.... The system validates this token before processing any synthesis job.

Generating your API key

Generating your API key

Keys are created on the /get-api-key/ page after signing in with Google or email. Google sign-ups receive a $0.50 trial credit valid for 7 days; email accounts start with zero balance.

  • Sign in via the /get-api-key/ page
  • Google accounts receive $0.50 trial credit
  • Email accounts start with no trial credit

Regenerating keys

You can issue a new key at any time from the dashboard. The old key stops working immediately, ensuring no overlap or accidental usage with the previous credential.

Endpoints Overview

Sound wave illustration for: Endpoints Overview

CivicSonic exposes a minimal REST interface for generating speech and discovering available resources. The primary endpoint accepts text payloads and returns audio files, while metadata endpoints list available voices and models.

POST /v1/audio/speech

This endpoint processes your input text and returns the synthesized audio file. You must provide a valid model, input text, and voice identifier. The service supports standard formats like MP3 and WAV, allowing direct integration into your existing media pipelines.

GET /v1/voices

Retrieve a list of all available voice presets, their associated languages, and supported audio formats. This endpoint helps you identify the correct voice ID for your specific language needs, such as Hindi or English, without making unnecessary API calls.

  • Voice ID and name
  • Supported languages
  • Available audio formats

GET /v1/models

Fetch the current list of supported TTS models. This allows your application to dynamically adjust to available engine versions or pricing tiers without hardcoding model identifiers.

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts standard request fields to control synthesis quality and output. You select a model, provide the text input, and choose a voice preset. Optional parameters allow you to adjust speed and specify a language code for accurate pronunciation.

Model selection (tts-1)

Choose between "tts-1" and "tts-1-hd". Both use the same engine and pricing tier, so the model choice affects only the output format quality, not the cost.

Input text limits

Each request supports up to 4096 characters. Spaces and punctuation count toward this limit. For longer documents, split the text into chunks and join the resulting audio files on the client side.

Voice and language settings

Select from eight voice presets, such as Aria or Felix. While the system guesses the language from the script, explicitly setting the ISO language code (e.g., "hi" for Hindi) ensures accuracy for non-English Latin-script text.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion
  • Speed range: 0.25–4.0
  • Supported formats: mp3, wav, opus, flac, pcm

Response Formats

Sound wave illustration for: Response Formats

The API returns the synthesized audio file directly in the response body, allowing for immediate playback or storage. You specify the desired output format via the response_format parameter to match your application’s needs, ensuring compatibility with various audio players and processing pipelines without requiring additional conversion steps.

For efficient integration, the response includes standard HTTP headers indicating content type and length. This structure simplifies parsing and error handling, letting your application focus on delivering audio to end-users rather than managing complex data streams or file metadata.

Audio file delivery

The primary response contains the raw audio data, ready for playback or saving to disk. This direct delivery method ensures predictable behavior for batch processing. The file is generated server-side and returned in a single HTTP response, eliminating the need for polling or WebSocket connections.

Supported formats

The API supports five audio formats: mp3, wav, opus, flac, and pcm. Choose mp3 or opus for smaller file sizes and efficient bandwidth usage, especially useful for mobile networks in diverse regions. Select wav or flac for high-fidelity storage or further editing. PCM provides uncompressed raw data for specific technical requirements.

Each format balances quality and size differently. Opus is a supported format. FLAC is a supported format. The choice depends on your audience’s devices and your storage constraints, allowing flexibility in how audio content is delivered.

  • mp3: Widely compatible, smaller file size
  • wav: Uncompressed, high quality
  • opus: Efficient compression for voice
  • flac: Lossless compression
  • pcm: Raw, uncompressed audio data

Error responses

If synthesis fails, the API returns an error code and message, with the charge returned in full. This ensures you are not billed for unsuccessful requests. Common errors include invalid parameters, rate limits, or insufficient balance. The response body includes details to help troubleshoot issues quickly, such as missing required fields or exceeded character limits.

Error handling is straightforward, with clear status codes and descriptive messages. This transparency helps developers identify and resolve issues promptly, maintaining reliability for critical audio delivery workflows. Regular monitoring of response codes can help anticipate and mitigate potential issues before they impact end-users.

Rate Limits

Sound wave illustration for: Rate Limits

Your API key allows up to 60 requests per minute once your account is active. This limit applies to all endpoints. Requests are processed sequentially, meaning generation time depends on text length and current queue status.

60 requests per minute

Each successful or failed request counts toward this limit. You can monitor your usage via the dashboard to plan batch operations effectively.

Initial limit before top-up

New accounts without a top-up start with a reduced limit of 10 requests per minute. This allows for initial testing without immediate consumption of your full quota.

Handling queue delays

Requests are processed one after another. Under high load, your request may wait in a queue before synthesis begins. Longer texts take more time, so plan your API calls accordingly to avoid delays in your workflow.

Rate Limits

Example: cURL Request

Sound wave illustration for: Example: cURL Request

Use cURL to send a POST request to the speech endpoint. Include your Bearer token in the Authorization header and define the model, voice, input text, and response format in the JSON body. The API returns the generated audio file directly in the response.

Basic Hindi text request

To generate audio in Hindi, send a POST request to https://api.ex66.info/v1/audio/speech. Specify the tts-1 model and a voice like nova. The input text must not exceed 4096 characters. Include your API key in the Authorization header.

Setting language code

Although the API can guess the language from the script, it is best practice to explicitly set the language parameter. For Hindi text, use "language": "hi". This ensures accurate pronunciation and prevents the system from defaulting to English for Latin-script text.

Specifying output format

You can choose the output format using the response_format field. Supported formats include mp3, wav, opus, flac, and pcm. For example, set "response_format": "mp3" for widely compatible audio files. The API returns the audio data directly in the response body.

Example: OpenAI SDK

Sound wave illustration for: Example: OpenAI SDK

Reusing the official OpenAI SDKs simplifies integration, requiring only a base URL adjustment and your API key. This approach leverages familiar libraries while directing requests to the CivicSonic infrastructure.

Authentication remains consistent with standard Bearer token protocols. Your unique key ensures secure access to the synthesis engine, maintaining the same request shape as the standard speech endpoint.

Changing base_url

Set the SDK's base URL to https://api.ex66.info/v1. This redirect ensures all synthesis requests route through the correct endpoint without modifying the core request body structure.

Using official SDKs

The OpenAI SDKs work directly by updating the base URL. This allows teams to use existing code patterns, reducing integration friction for NGOs and public service teams already familiar with standard TTS workflows.

Authentication setup

Pass your API key in the Authorization header as 'Bearer tts-...'. Ensure the key is active and has sufficient balance, as failed requests are free but valid keys are required for processing.

Handling Long Texts

Sound wave illustration for: Handling Long Texts

Your TTS API accepts a maximum of 4,096 characters per request. For longer documents, such as monthly reports or detailed policy guides, you must split the input text into chunks that respect this limit before sending them to the endpoint.

Splitting at 4096 characters

Divide your source text into segments of up to 4,096 characters each. Spaces and punctuation count toward this total. Ensure boundaries do not cut mid-sentence to maintain audio coherence when the segments are played sequentially.

Joining audio files

Each API call returns a separate audio file. Your application must concatenate these files in the correct order to form a single continuous audio stream. This ensures listeners experience the content without abrupt pauses between sections.

Client-side processing

Handle this splitting and joining logic on the client side or within your backend service. Since the API does not manage long-form content natively, your code must track the chunk index and manage the final assembly of the audio data.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. The platform is designed for large enterprises, often including features and support levels that small NGOs may not need.

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

More on this site