Start Generating Speech with cURL and Python

By EchoServe editorial team · Updated 2026-11-18

This guide demonstrates how to integrate the EchoServe text-to-speech API using cURL and Python, tailored for public service and NGO product teams. You will learn to configure authentication, structure JSON requests, and manage audio generation for accessibility and compliance workflows. We cover essential parameters like voice selection, speed adjustment, and language detection, ensuring your implementation meets specific project requirements without unnecessary complexity.

Readers will find concrete examples for generating speech in 23 supported languages (Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish)., handling rate limits of 60 requests per minute, and understanding cost implications at $0.01 per 1,000 characters. The guide also explains how to use the official OpenAI SDK with our base URL, manage audio formats like MP3 and WAV, and handle errors where failed requests incur no charge. This resource provides the factual details needed for efficient, compliant TTS integration.

Start Generating Speech with cURL and Python

Frequently asked questions

How do I change the base URL in the OpenAI SDK?

Set the base_url parameter to https://api.playtk77.com/v1. The API follows the same request shape as OpenAI, so standard OpenAI SDKs work by updating this endpoint and using your EchoServe API key for authentication.

What is the maximum input length for a single request?

The maximum input length is 4096 characters per request. For longer texts, you must split the content into parts of up to 4096 characters, generate audio for each part, and then join the resulting audio files.

Can I generate audio in multiple formats simultaneously?

No, each request generates a single audio file in one format. You can choose from mp3, wav, opus, flac, or pcm by setting the response_format field in your JSON body for each individual synthesis request.

How do I specify the language for Latin-script text?

Set the optional language parameter to the ISO code. If omitted, the API guesses the language, defaulting to English for Latin-script text. Explicitly setting it ensures correct pronunciation for non-English Latin-script content.

Does the API support streaming audio 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. Requests are processed sequentially, so long texts may experience queue delays.

Is SSML supported for formatting?

No, the API does not support SSML. It accepts plain text input up to 4096 characters. There are no emotion tags, phoneme dictionaries, or custom pronunciation lexicons available for formatting the speech output.

What happens if I send text longer than 4096 characters?

The API rejects the request if the input exceeds 4096 characters. You must manually split the text into smaller chunks, send separate requests for each chunk, and then concatenate the returned audio files.

How do I handle rate limit errors?

The limit is 60 requests per minute per key (10 before top-up). Implement exponential backoff in your client code to retry after receiving a rate limit error, ensuring you stay within the allowed threshold.

Can I use the same key for multiple projects?

Yes, each account has one active key that can be used across multiple projects. You can issue a new key at any time, which immediately invalidates the old one, allowing you to rotate credentials.

Is the API key case-sensitive?

Yes, the API key is case-sensitive. Include it in the Authorization header as 'Bearer tts-...' exactly as provided in your account dashboard. Incorrect casing will result in authentication failure.

Do I need to install a specific library?

No, you do not need a proprietary library. You can use the official OpenAI SDK by changing the base URL, or use any standard HTTP client library to send POST requests to the speech endpoint.

Is the response binary or base64 encoded?

The response contains the raw binary audio data for the requested format. It is not base64 encoded. You should handle the response body as a binary stream and save it directly to a file.

How do I verify my API key is active?

Make a simple request to the /v1/voices endpoint or attempt a small synthesis. If the key is active, you receive a valid response. If invalid, you receive an authentication error.

Can I retrieve usage statistics via the API?

No, there is no dedicated endpoint for real-time usage statistics. You can view your balance, characters left, and usage history on the /get-api-key/ page in your account dashboard.

First request

curl

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

Authentication for the EchoServe TTS API relies on a single active Bearer token per account. Include the header Authorization: Bearer tts-... in every request to identify your account and authorize usage against your balance.

Bearer token header

Pass your API key in the Authorization header of each HTTP request. The format is strictly Bearer tts-<your_key>. This header is required for all endpoints, including voice listing and speech synthesis.

Key format: tts-...

Keys always begin with the prefix tts-. You can generate a new key at any time via the dashboard; the previous key becomes invalid immediately.

One active key per account

Each account maintains exactly one active key. Revoking or regenerating the key stops the old one instantly, ensuring tight control for compliance and security audits.

Endpoint Configuration

Sound wave illustration for: Endpoint Configuration

Send text-to-speech requests to the speech endpoint. The API accepts JSON payloads and returns audio files directly in the response body.

POST /v1/audio/speech

Use the HTTP POST method to send your text for synthesis. The endpoint processes requests sequentially, so under load, synthesis may wait in a queue.

Base URL modification

Set your request base URL to https://api.playtk77.com/v1. This allows standard OpenAI SDKs to work by simply overriding the base URL configuration.

JSON request body

Include your text, model choice, voice preset, and audio format in a single JSON object. The request must not exceed 4096 characters per call.

Endpoint Configuration

Required Parameters

Sound wave illustration for: Required Parameters

To generate speech, you must specify the model, input text, and voice. The API accepts "tts-1" or "tts-1-hd", both using the same engine and pricing. This ensures consistent audio quality regardless of the selected tier, as both models use the same engine.

Model selection (tts-1)

Both "tts-1" and "tts-1-hd" utilize the identical underlying engine, meaning there is no difference in audio output or pricing. You may choose either based on your preference, as the cost remains fixed at $0.01 per 1,000 characters for both options.

Input text string

Provide your text in the input field, limited to 4096 characters per request. Spaces and punctuation count toward this limit. For longer content, split the text into parts and join the resulting audio files.

  • Maximum length: 4096 characters per request
  • Spaces and punctuation count as characters
  • Split longer texts into multiple requests

Voice preset ID

Select one of the eight voice presets, such as "aria" or "felix". Each voice is based on licensed recordings from LibriTTS-R. You can choose from female voices like "nova" or male voices like "atlas" to suit your content's tone.

  • aria: warm, clear narrator
  • nova: bright, upbeat
  • luna: soft, storytelling
  • sage: calm, instructional
  • felix: energetic, promo
  • milo: friendly, conversational

Optional Parameters

Sound wave illustration for: Optional Parameters

The API accepts optional parameters to refine output quality and language detection. While the request shape mirrors OpenAI’s standard, these fields allow you to tailor the synthesis without changing the core endpoint structure.

Response format selection

You can choose from mp3, wav, opus, flac, or pcm. Use mp3 for web compatibility or WAV for high-fidelity archival needs. The format does not affect pricing or character counting.

  • mp3: Standard web audio
  • wav: Lossless quality
  • opus: Efficient compression
  • flac: Lossless compression
  • pcm: Raw uncompressed audio

Speed adjustment (0.25-4.0)

Adjust speech speed between 0.25 and 4.0. This is useful for accessibility or fitting specific word counts into time-limited media. Values outside this range are rejected.

  • Minimum speed: 0.25x
  • Maximum speed: 4.0x
  • Default: 1.0x

Language ISO code

Specify the ISO language code (e.g., 'en', 'de', 'ja') to ensure correct pronunciation. If omitted, the system guesses from the script, defaulting to English for Latin text.

  • Supported: 23 languages
  • Optional field
  • Auto-guessing available

Audio Formats

Sound wave illustration for: Audio Formats

The API returns audio in MP3, WAV, Opus, FLAC, or PCM formats. MP3 is ideal for web playback, while WAV ensures high fidelity. Opus and FLAC provide efficient compression and lossless quality options respectively.

MP3 for web compatibility

MP3 is the recommended format for web applications and mobile clients. It offers a balance of file size and audio quality, ensuring broad compatibility across browsers and devices without additional codec requirements.

WAV for high quality

WAV provides lossless audio, preserving the full fidelity of the generated speech. This format is suitable for archival purposes, professional editing workflows, or scenarios where maximum audio clarity is required without compression artifacts.

Opus and FLAC options

Opus offers high-quality audio at lower bitrates, ideal for bandwidth-constrained environments. FLAC provides lossless compression, reducing file size while retaining all original audio data.

Audio Formats

Rate Limits

Sound wave illustration for: Rate Limits

Your API key supports 60 requests per minute under normal conditions. This limit applies per key, not per account, so generating multiple audio files simultaneously is efficient for batch processing accessibility content. Requests are processed sequentially, meaning the actual throughput depends on text length and server load.

Before your first top-up, you are limited to 10 requests per minute. This allows product teams to verify voice quality and format compatibility without immediate billing pressure. Once USDT (TRC-20) is credited, the standard rate limit activates automatically.

60 requests per minute

The standard rate limit allows 60 requests per minute per active key. This capacity supports typical NGO or public service workflows where batch document-to-speech conversions occur.

10 requests before top-up

New accounts start with a stricter limit of 10 requests per minute. This ensures fair usage during the free trial phase, which includes $0.50 credit valid for 7 days (for Google sign-ins).

Queued processing under load

Requests are processed one after another. Under heavy load, a request may wait in a queue, extending generation time beyond the typical 25 characters per second. Short phrases may take a few seconds regardless of queue status.

Failed requests incur no charge, so waiting in queue does not increase cost if the synthesis ultimately fails.

Error Handling

Sound wave illustration for: Error Handling

Synthesis failures are fully refunded. If the API returns an error during processing, you pay nothing for that request. This protects your budget when network issues or temporary engine delays occur. You only pay for successfully generated audio files. This rule applies to all models and formats without exception.

The system returns standard HTTP error codes (4xx for client errors, 5xx for server issues) to indicate the failure type. Failed requests do not consume your character allowance, ensuring accurate billing tracking. You can retry failed requests immediately without penalty, as long as you stay within your rate limits.

Failed requests are free

If synthesis fails, the charge is returned in full. You are not billed for text that did not produce an audio file. This includes cases where the engine times out or returns an unexpected error state. Your balance remains untouched, preserving your credit for subsequent successful requests.

  • No charge for failed synthesis attempts
  • Balance is not deducted for errors
  • Retry immediately without penalty

Standard HTTP error codes

The API uses standard HTTP status codes to communicate errors. Use 400-level codes to correct request parameters, such as invalid voice IDs or exceeded character limits. 500-level codes indicate temporary server issues; wait a few seconds and retry. Check the response body for detailed error messages to debug quickly.

  • 400: Invalid request parameters
  • 401: Authentication failure
  • 429: Rate limit exceeded
  • 500: Internal server error

No charge on synthesis failure

Every failed request triggers an automatic refund if any charge was applied. This ensures you only pay for usable audio. You can verify the lack of charge in your account dashboard. Failed requests are marked clearly, so you can distinguish them from successful generations for accurate cost tracking.

  • Automatic refund for errors
  • Zero cost for failed audio generation
  • Clear billing history for audits
Error Handling

SDK Integration

Sound wave illustration for: SDK Integration

The EchoServe API is fully compatible with the official OpenAI Python SDK. By simply adjusting the client configuration, product teams can leverage the same reliable codebase used by thousands of developers without learning a new interface.

This approach minimizes integration effort for public service and NGO engineering teams, allowing them to focus on accessibility features rather than API boilerplate.

Use official OpenAI SDK

Import the standard OpenAI library as you normally would. This ensures you benefit from the SDK’s established stability and community support.

Override base_url

Set the base_url parameter to https://api.playtk77.com/v1. This redirects all requests to our endpoint while keeping the SDK structure intact.

Same request shape

The JSON body structure remains identical to the OpenAI standard. You continue using the same model, input, and voice fields without modification.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Our platform empowers public service teams to deliver seamless, inclusive digital experiences for every citizen, everywhere.

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. Python documentation
  3. W3C WAI: making audio and video accessible
  4. LibriVox public-domain audiobooks
  5. ISO 639 language codes
  6. curl documentation
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. MDN: Web Speech API
  9. IETF RFC 7845: Ogg Opus
  10. Node.js documentation
  11. Creative Commons Attribution 4.0
  12. Tether (USDT)

More on this site