Cloud Text-to-Speech API: Integration Guide

By IVR Voice editorial team · Updated 2026-11-19

This guide helps product teams integrate IVR Voice into call centers and support bots. You will learn to send text and receive audio files via a standard REST API that mimics the OpenAI speech endpoint, ensuring quick adoption for existing engineering teams.

We cover authentication, request parameters, and rate limits specific to conversational flows. You will find concrete examples for curl, Python, and Node.js, along with strategies for handling text splitting and speed adjustments to maintain natural latency in your telephony systems.

Cloud Text-to-Speech API: Integration Guide

Frequently asked questions

How do I get an API key?

Visit /get-api-key/ to sign up with Google or email. Google sign-ins receive a $0.50 free trial valid for 7 days. Email accounts start with zero credit. You receive one active key per account, which you can replace anytime via the dashboard.

What is the base URL?

The API base URL is https://api.0000ff.info/v1. Use this endpoint for all requests. Authentication requires an Authorization header with your Bearer token. The standard speech endpoint is POST /v1/audio/speech. Other endpoints include GET /v1/voices and GET /v1/models.

Can I use the OpenAI SDK?

Yes. The request shape matches the OpenAI speech endpoint. Configure your SDK’s base_url to https://api.0000ff.info/v1 and use your site’s key. This allows immediate integration using official OpenAI SDKs without learning a new library or adapting to a different API structure.

What models are available?

Two models exist: tts-1 and tts-1-hd. Both use the same engine and price. Select the model in your request body. The choice affects audio quality but not the cost or character pricing. Both models support all eight voice presets and standard parameters.

What is the character limit?

Each request supports up to 4096 characters. Spaces and punctuation count toward this limit. For longer texts, split the input into chunks of 4096 characters. Generate audio for each chunk and join the resulting files to create the complete audio output.

How do I set the language?

Pass the optional language parameter as an ISO code. If omitted, the system guesses the language from the script. Latin text defaults to English. For non-English Latin text, explicitly set the language to ensure accurate synthesis and avoid misinterpretation of accents.

What audio formats are supported?

Supported formats are mp3, wav, opus, flac, and pcm. Specify the desired format in the response_format field. All formats are generated instantly upon successful synthesis. Choose based on your storage needs or playback requirements. Failed requests return no audio and charge nothing.

What is the speed range?

Adjustable speed ranges from 0.25 to 4.0. This allows slowing down narration or speeding up quick updates. The default speed provides natural conversation flow suitable for IVR. Adjustments do not affect pricing or character limits. Use this to fit audio into specific time windows.

How do I handle rate limits?

Limits are 60 requests per minute per key. New accounts start with 10 requests per minute until the first top-up. Monitor your usage via the dashboard. Implement retry logic with exponential backoff if you approach these limits during high-volume IVR deployment scenarios.

What happens if I exceed limits?

Requests may queue or fail if you exceed the rate limit. Failed requests are free; the charge is returned in full. Ensure your application handles HTTP errors gracefully. Use the dashboard to monitor real-time usage and adjust your request volume accordingly.

Is there a WebSocket endpoint?

No, there is no WebSocket endpoint for streaming audio. The API returns complete audio files via standard HTTP responses. You must wait for the full file to download before playing it, as there is no streaming. This suits batch processing but not real-time partial audio streaming.

Do I need to install a specific SDK?

No specific SDK is required. Use the official OpenAI SDK or plain HTTP. Configure the base URL to our API endpoint. This approach avoids vendor lock-in and allows integration with any language or framework that supports standard HTTP requests and JSON.

How do I split long texts?

Split text into parts of up to 4096 characters. Send each part to the speech endpoint. Join the resulting audio files sequentially. This ensures consistent quality and avoids truncation. Monitor character counts carefully, as spaces and punctuation count toward the limit.

What is the response format?

The response contains the audio file in the requested format. Metadata like time, characters, and status are kept for billing. The audio file is not stored on our servers. Failed requests return an error status and no audio, and the charge is returned in full.

First request

curl

curl https://api.0000ff.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.0000ff.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.0000ff.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 for the IVR Voice API relies on a single active API key per account. You generate this key on the /get-api-key/ dashboard, where it is displayed alongside your current balance and usage statistics.

Each key is unique to your account and provides full access to all endpoints. You can revoke the current key and issue a new one at any time; the old key becomes invalid immediately upon generation.

API Key Format

API Key Format

Your API key is a string starting with the prefix tts-, followed by a sequence of alphanumeric characters. This format is consistent across all requests to ensure secure identification of your account.

Bearer Token

Bearer Token

Include your key in the HTTP header using the standard Bearer authentication scheme. The header must be formatted exactly as: Authorization: Bearer tts-....

  • Key example: Authorization: Bearer tts-abc123def456
  • Case-sensitive header name: Authorization
  • Prefix must be Bearer (with a space)

Key Management

You may issue a new key at any time from your dashboard. Once generated, the previous key stops working instantly, allowing for rapid rotation without downtime.

  • One active key per account
  • Old keys invalidate immediately
  • No key expiration by default

Endpoint Overview

Sound wave illustration for: Endpoint Overview

The API exposes three primary endpoints for managing text-to-speech generation and configuration. Use the speech endpoint to convert text into audio, the voices endpoint to discover available presets and pricing, and the models endpoint to verify engine details.

All endpoints reside under the base URL https://api.0000ff.info/v1. Authentication is required via the Authorization header for all requests.

Speech Endpoint

Send a POST request to /v1/audio/speech with a JSON body containing the text, voice, and format. The endpoint returns the audio file directly or an error object if synthesis fails. Text is limited to 4,096 characters per request.

  • POST https://api.0000ff.info/v1/audio/speech
  • Accepts model, input, voice, response_format, and speed parameters
  • Returns audio binary or JSON error

Voices Endpoint

Use GET /v1/voices to retrieve a list of all available voice presets, supported languages, and output formats. This endpoint helps you select the appropriate voice for your IVR or bot context before making synthesis requests.

  • GET https://api.0000ff.info/v1/voices
  • Returns voice ID, name, gender, and supported languages
  • Includes format and pricing metadata

Models Endpoint

Access GET /v1/models to confirm the available TTS engines. Currently, "tts-1" and "tts-1-hd" share the same engine and pricing structure. Use this endpoint to verify model availability without guessing parameter values.

  • GET https://api.0000ff.info/v1/models
  • Returns model ID, name, and capabilities
  • Confirms tts-1 and tts-1-hd availability

Request Parameters

Sound wave illustration for: Request Parameters

Configure your synthesis requests with three core parameters: the model engine, the input text, and the voice preset. These fields define how your IVR or bot audio is generated, ensuring the output matches your system's latency and tone requirements.

Model Selection

Choose between "tts-1" or "tts-1-hd". Both use the same engine and pricing, so select based on your quality preference without worrying about cost differences.

Input Text

Pass your script as the input field. The API supports up to 4096 characters per request. For longer IVR menus, split the text into chunks and join the resulting audio files.

  • Max 4096 characters per request
  • Spaces and punctuation count toward the limit
  • Split and join for longer flows

Voice Preset

Select one of eight presets tailored for different tones. Use "atlas" for neutral news-style prompts or "milo" for friendly, conversational support interactions. All voices support 23 languages.

  • 8 distinct voice presets
  • Supports 23 languages
  • Optional language ISO code override

Response Formats

Sound wave illustration for: Response Formats

When the synthesis succeeds, the API returns the audio file directly as the response body, allowing your application to stream or save the binary data immediately.

This direct binary response ensures low latency, which is critical for IVR systems where every millisecond affects the caller's perception of natural conversation flow.

Audio Binary

The response body contains the raw audio bytes in the format you requested (mp3, wav, opus, flac, or pcm). No JSON wrapper is used for the audio data itself, keeping parsing overhead minimal for your integration.

JSON Metadata

Standard HTTP headers provide metadata, but the API does not return a JSON object with usage details in the success response. You must track character counts locally based on your input length, as the response body is purely audio.

Note that generated files carry an inaudible watermark marking them as synthetic speech, though this is not exposed in the metadata.

Error Codes

Non-200 status codes indicate failure, such as 401 for invalid keys or 429 for rate limits. Failed requests are free, so you can retry without worrying about unnecessary charges.

Always check the HTTP status code rather than parsing the body for errors, as the body may be empty or malformed during transport issues.

Rate Limits

Sound wave illustration for: Rate Limits

Your API key allows 60 requests per minute once active, with a stricter limit of 10 requests per minute for new accounts before the first top-up. This structure ensures fair usage while preventing sudden bursts from overwhelming the synthesis engine.

Requests Per Minute

The standard rate limit is 60 requests per minute per key. If your account is new, this limit starts at 10 requests per minute until you add credit via USDT on the TRON network (TRC-20). Requests are processed sequentially, so high-volume IVR systems should batch their calls to stay within these bounds.

Queue Behavior

Requests are processed one after another. Under load, a request may wait in a queue before synthesis begins. For IVR use cases, this means generation starts immediately for short phrases but may delay for longer texts. Typical speed is roughly real-time, producing about 25 characters of text per second of audio.

Burst Limits

There is no hard burst limit beyond the per-minute cap. However, sending many large payloads simultaneously can increase latency due to sequential processing. Plan your integration to send requests steadily rather than in massive bursts to maintain consistent latency for your support bots.

Rate Limits

Code Examples

Sound wave illustration for: Code Examples

Use these examples to integrate IVR Voice into your call center stack. The API accepts standard JSON payloads, making it easy to generate audio for support bots without complex middleware.

Below are ready-to-run snippets for quick validation. Adjust the model and voice parameters to match your specific IVR use case, such as using "atlas" for news-style updates or "nova" for upbeat prompts.

curl Command

Test the endpoint directly from your terminal. Replace YOUR_API_KEY with your key from /get-api-key/. This command generates a 2-second MP3 clip of the "nova" voice.

  • Endpoint: POST https://api.0000ff.info/v1/audio/speech
  • Auth: Authorization: Bearer tts-...
  • Body: `{"model": "tts-1", "voice": "nova", "input": "Welcome to support.", "response_format": "mp3"}`

Python SDK

Use the official OpenAI SDK with a custom base URL. This approach works because our request shape matches the OpenAI standard. Install openai and point it to our API base.

  • Set base_url="https://api.0000ff.info/v1"
  • Use openai.audio.speech.create()
  • Handle audio bytes directly for IVR playback

Node.js Example

Fetch the audio buffer and pipe it to your telephony provider. The response contains binary audio data, not a URL. Ensure you handle the Content-Type header correctly for WAV or MP3 outputs.

Error Handling

Sound wave illustration for: Error Handling

Synthesis failures are free, ensuring you are never charged for audio that never arrives. Understanding the specific error code helps you resolve issues quickly without wasting credits.

Common Errors

You may encounter a 400 error if the input text exceeds 4,096 characters or if the voice ID is invalid. A 429 error indicates you have hit the rate limit (60 requests per minute for active accounts, 10 for new accounts).

Retry Logic

Implement exponential backoff for 429 errors. Since requests are processed sequentially, a brief pause often resolves queue congestion without additional cost.

Debugging Tips

Verify your Authorization header starts with 'Bearer '. Use the /v1/voices endpoint to confirm your selected voice ID exists before making speech requests.

  • Check for network timeouts on long audio generations.
  • Ensure text encoding is UTF-8.

Advanced Usage

Sound wave illustration for: Advanced Usage

Beyond basic synthesis, the API offers granular control over voice pacing, language detection, and handling of long texts. These features ensure the generated audio fits seamlessly into IVR menus or conversational bots without awkward pauses or mispronounced phrases.

Speed Control

Adjust the speed parameter between 0.25 and 4.0 to match your IVR’s pacing. Slower speeds improve clarity for complex menu instructions, while faster rates keep interactive flows concise. Adjustments apply to all voices equally.

Language Override

While the API guesses language from script, you can explicitly set the language field using ISO codes. This is critical for non-English Latin-script text (e.g., Dutch or German) to prevent defaulting to English pronunciation.

Text Splitting

Each request accepts up to 4096 characters. For longer prompts, split your text into chunks, generate audio for each, and join the files client-side. This ensures consistent quality and avoids truncation during synthesis.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This model scales naturally with your call volume, whether you handle a few hundred or millions of interactions monthly.

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. W3C WAI: making audio and video accessible
  3. Creative Commons Attribution 4.0
  4. TRON developer hub: TRC-20
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. ISO 639 language codes
  7. Node.js documentation
  8. Tether (USDT)
  9. Python documentation
  10. curl documentation
  11. LibriTTS-R corpus (OpenSLR 141)
  12. IETF RFC 7845: Ogg Opus

More on this site