EchoLoom API Documentation: Text-to-Speech Guide

By EchoLoom editorial team · Updated 2026-11-18

This guide shows mobile app developers how to integrate EchoLoom’s text-to-speech API into their iOS and Android applications. You will learn to generate high-quality audio from text using standard HTTP requests, manage voice parameters, and handle billing details. The documentation covers practical workflows for startups that need reliable speech synthesis without managing complex infrastructure.

We provide concrete examples, including cURL commands and OpenAI SDK integration, to help you get started quickly. You will find details on available voices, supported languages, rate limits, and error handling. This resource is designed for engineering teams building apps that require clear, natural-sounding audio output with minimal integration overhead.

EchoLoom API Documentation: Text-to-Speech Guide

Frequently asked questions

How do I get an API key?

Navigate to /get-api-key/ and sign up using Google or an email and password. The dashboard displays your active API key, which you use with the Bearer token authentication header. You can generate a new key at any time, which immediately invalidates the previous one.

What is the base URL?

The API base URL is https://api.playtt39.com/v1. You send POST requests to /audio/speech for synthesis. You can also use GET /v1/voices to list available voices or GET /v1/models to check model details. This endpoint structure mirrors the standard OpenAI speech API format.

Does the API support OpenAI SDK?

Yes, the official OpenAI SDKs work perfectly. Simply change the base_url configuration to https://api.playtt39.com/v1 and provide your EchoLoom API key. The request shape matches the OpenAI speech endpoint exactly, allowing you to use existing code with minimal configuration changes for integration.

What formats are supported?

The API supports five audio formats: mp3, wav, opus, flac, and pcm. You specify the desired format using the response_format field in your JSON request body. Each generated file includes an inaudible watermark to identify it as synthetic speech, ensuring clear attribution for your users.

What are the rate limits?

You are limited to 60 requests per minute per API key. Before your first top-up, this limit is reduced to 10 requests per minute. Requests are processed sequentially, so high load may cause queuing delays. Failed requests do not count against your balance.

How do I handle long texts?

Split your input text into chunks of up to 4096 characters. Send each chunk as a separate request to the /audio/speech endpoint. Then, programmatically join the returned audio files to create a single continuous audio file. This ensures optimal processing speed and reliability for longer content.

Is there an error code for rate limits?

The API uses standard HTTP status codes to indicate errors. When you exceed the 60 requests per minute limit, you will receive a 429 Too Many Requests response. Your client should handle this by implementing exponential backoff or waiting until the rate limit window resets before retrying.

Can I regenerate my API key?

Yes, you can issue a new API key at any time from your dashboard. Once the new key is generated, the old key stops working immediately. This allows you to rotate keys securely without downtime. You can maintain one active key per account for simplicity.

What happens if I send an invalid voice?

If you provide a voice name not in the list of eight presets, the API returns an error. The request will fail, and you will not be charged for the characters processed. You can retrieve the valid voice list by sending a GET request to /v1/voices.

How do I set the language?

Include the language field with an ISO code in your request body. If omitted, the system guesses the language based on the text script, defaulting to English for Latin text. For non-English Latin scripts, explicitly setting the language ensures accurate synthesis and prevents mispronunciation errors.

Does the API return streaming data?

No, the API does not support streaming or WebSocket connections. It returns the complete audio file in the response body after synthesis is finished. Short phrases take a few seconds, while longer texts take roughly real-time duration. You must wait for the full response before playing audio.

Is there a WebSocket endpoint?

No, there is no WebSocket endpoint available. The API is strictly HTTP-based, using POST for speech generation and GET for metadata retrieval. All audio data is returned as a complete file in the response payload, requiring standard HTTP client handling rather than persistent connections.

How do I handle failed requests?

If synthesis fails, the charge is returned in full to your balance. Failed requests do not consume your character quota. You should implement logic to check the HTTP status code and retry or alert users if the audio generation fails unexpectedly.

What is the maximum text length?

The maximum input text length is 4096 characters per request. Spaces and punctuation count toward this limit. For texts longer than 4096 characters, you must split the text into multiple requests, generate audio for each part, and then join the resulting audio files sequentially.

First request

curl

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

Get Your API Key

Sound wave illustration for: Get Your API Key

Access the EchoLoom API to generate speech for your mobile application. This resource is designed for engineering teams building apps that require clear audio output with minimal integration overhead. You will create an account and retrieve a unique key to authenticate your requests.

Sign Up

Sign Up

Navigate to the /get-api-key/ page to create your account. You can sign in using Google or provide an email and password. Google sign-in grants a free trial with $0.50 credit valid for 7 days, while email accounts start without trial credit.

Generate Key

Generate Key

After signing in, the dashboard displays your API key, current balance, and usage statistics. Your key begins with tts- and is used for authentication. Each account has one active key at a time.

Manage Keys

You can issue a new key at any time from the dashboard. When a new key is generated, the previous one becomes invalid immediately. This ensures secure access control as your team grows or roles change.

First Request

Sound wave illustration for: First Request

Send a POST request to the speech endpoint with your text and voice selection. The API returns a single audio file based on the model and parameters provided.

cURL Example

Use the following command to generate speech. Replace YOUR_API_KEY with your token from the dashboard.

  • curl -X POST https://api.playtt39.com/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 body must be JSON. Supported fields include model ("tts-1" or "tts-1-hd"), input text (max 4096 characters), voice preset, response format, and optional speed or language codes.

Response Format

On success, the response contains the audio file in your requested format (mp3, wav, opus, flac, or pcm). Failed requests return an error object but incur no charge.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

The EchoLoom API mirrors the OpenAI speech endpoint structure, allowing you to use official OpenAI SDKs with minimal configuration. By simply adjusting the base_url to point to our infrastructure, your existing code can route requests to EchoLoom without rewriting the core logic.

This approach lets your mobile app team leverage familiar libraries while benefiting from our specific billing and voice features. You only need to update the endpoint URL and inject your unique API key for authentication.

Base URL Change

Set your SDK client's base URL to https://api.playtt39.com/v1. This directs all API calls to EchoLoom's servers while maintaining the standard OpenAI request shape.

Client Setup

Initialize your client using the standard OpenAI SDK pattern. Pass your API key via the Authorization: Bearer header or the SDK's key parameter. Ensure you are using a recent version of the library that supports custom base URLs.

Code Example

  • Configure the OpenAI client with the new base URL
  • Pass the model, input, voice, and response_format parameters
  • Send the request and receive the audio file directly in the response

Voices and Parameters

Sound wave illustration for: Voices and Parameters

The API supports eight distinct voice presets, categorized by gender and tone. Female voices include Aria for clear narration, Nova for upbeat content, Luna for storytelling, and Sage for instructional material. Male options feature Felix for energetic promos, Milo for conversational tones, Atlas for neutral news delivery, and Orion for deep documentary styles. Each voice is derived from licensed LibriTTS-R recordings.

All voices support any of the 23 available languages, allowing flexible mixing without needing separate voice models. The system generates synthetic speech with an inaudible watermark in every file.

Voice Selection

Choose a voice by passing its name (e.g., 'aria', 'nova') in the voice field. The model parameter accepts either 'tts-1' or 'tts-1-hd', using the same engine for both. Select based on your app's context: use Luna for calm storytelling or Felix for promotional segments.

  • 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

Speed Control

Adjust speech rate using the speed parameter, accepting values between 0.25 and 4.0. The default speed is 1.0. Faster speeds reduce generation time but may affect clarity, while slower speeds enhance comprehension for complex content. Test with short phrases first to ensure quality matches your user experience goals.

Language Setting

Pass the language field with an ISO code (e.g., 'en', 'de', 'ja') to ensure accurate pronunciation. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language prevents errors with non-English Latin-script text or ambiguous inputs. Supported languages include Arabic, Chinese, French, German, Hindi, Japanese, Korean, Spanish, and others listed in the API reference.

Response Formats

Sound wave illustration for: Response Formats

The API returns audio files directly in the response body, allowing your mobile app to save the content immediately. You can choose the format that best balances quality, file size, and compatibility for your specific use case.

MP3 Support

MP3 is a recommended format for most mobile applications. It offers an excellent balance between audio quality and file size, ensuring faster loading times and reduced bandwidth usage for your users.

WAV Support

WAV provides uncompressed, lossless audio. Use this format when you need the highest fidelity for voice playback.

Other Formats

You can also request Opus, FLAC, or PCM formats via the response_format parameter. Opus is efficient for variable bitrates, FLAC offers lossless compression, and PCM provides raw uncompressed data for immediate processing.

Response Formats

Rate Limits

Sound wave illustration for: Rate Limits

EchoLoom enforces a standard rate limit of 60 requests per minute per API key. This limit applies to all successful and failed requests, ensuring fair usage across the network. Requests are processed sequentially, so under heavy load, synthesis may queue briefly.

Requests Per Minute

Each API key supports up to 60 requests per minute. This capacity is sufficient for most mobile app integrations, including batch processing and real-time user interactions. Failed requests do not count against your balance, though they still consume part of your rate limit quota.

  • Standard limit: 60 requests/minute per key
  • Requests are processed sequentially
  • Queuing may occur under load

Pre-Trial Limit

Accounts without a top-up are restricted to 10 requests per minute. This lower limit helps manage infrastructure costs for free trial users. Once you add USDT (TRC-20), your limit automatically increases to the standard 60 requests per minute.

  • Trial accounts: 10 requests/minute
  • Top-up removes the restriction
  • Automatic upgrade upon payment

Handling Limits

If you exceed the rate limit, the API returns a 429 Too Many Requests error. Implement exponential backoff in your application to retry requests after a short delay. Monitor your usage via the dashboard to anticipate peak times and adjust your request volume accordingly.

  • 429 error when limit exceeded
  • Use exponential backoff for retries
  • Monitor usage in dashboard

Error Handling

Sound wave illustration for: Error Handling

Errors are handled via standard HTTP status codes and a JSON body containing an error object with a code and message. This allows your mobile app to distinguish between transient network issues and permanent failures like invalid input.

When a request fails, the synthesis is not charged. You receive a full credit refund immediately, so you can safely retry or alert the user without worrying about billing discrepancies.

Common Errors

Use the provided error codes to debug quickly. Common issues include input_too_long if the text exceeds 4096 characters, or invalid_voice if the preset name is misspelled.

Always validate the input field length before sending the request to avoid wasting API calls.

  • 400 Bad Request: Invalid parameters or missing fields.
  • 401 Unauthorized: Expired or incorrect API key.
  • 429 Too Many Requests: Rate limit exceeded.

Retry Logic

Implement exponential backoff for 5xx server errors or 429 rate limit responses. Start with a 1-second delay and double it for each retry, up to three attempts.

Since requests are processed sequentially, brief pauses between retries help avoid queue congestion during high load.

Billing Errors

If a synthesis fails, the charge is returned in full. Your balance will reflect this refund automatically.

Check your dashboard at /get-api-key/ to verify that credits were restored after a failed request.

Best Practices

Sound wave illustration for: Best Practices

Optimize your mobile app’s performance by adhering to the 4,096 character limit per request. For longer content, split the text into manageable chunks, generate each segment, and concatenate the resulting audio files to ensure seamless playback.

Long Text Handling

Split input text into segments of up to 4,096 characters. This ensures reliable processing and avoids request failures. Combine the resulting audio files sequentially to maintain continuity for the user.

  • Max 4,096 characters per request
  • Split text logically (e.g., by sentence)
  • Concatenate output files for playback

Audio Joining

Use a library compatible with your chosen format (MP3, WAV, etc.) to merge audio segments. Ensure consistent sample rates and formats across all parts to prevent playback glitches in your mobile app.

Caching

Cache generated audio files for identical text inputs. Since generation takes time (roughly 25 characters per second), caching reduces latency and API usage for recurring content like app instructions or menus.

  • Cache by exact input text
  • Reduce API calls for static content
  • Minimize user wait times

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. OPUS offers efficient compression for mobile data, while WAV provides uncompressed quality for high-fidelity needs.

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. LibriTTS-R corpus (OpenSLR 141)
  4. Tether (USDT)
  5. W3C WAI: making audio and video accessible
  6. TRON developer hub: TRC-20
  7. MDN: Web Speech API
  8. openai-python on GitHub
  9. LibriVox public-domain audiobooks
  10. FFmpeg documentation
  11. ISO 639 language codes
  12. IETF RFC 7845: Ogg Opus

More on this site