API Version 1.0

Developer Documentation

Integrate ECHO's powerful translation engines into your applications. Our API offers speech-to-speech, text-to-speech, speech-to-text, and comprehensive document translation endpoints.

Authentication

Authenticate your requests by including your Client ID and Client Secret in the HTTP headers. You can manage your credentials in the API Keys Dashboard.

HEADERS

X-Client-Id: your_client_id_here
X-Client-Secret: your_client_secret_here

Note: API requests are metered in USD and deduct from your universal wallet balance. Keep your balance topped up to ensure uninterrupted service!

Core Endpoints

Translate Text (Text to Text)

POST

/api/v1/translation/text/

Translates text instantaneously from a source language to a target language.

Request Payload

{
  "text": "Hello, how are you?",
  "source_language": "en",
  "target_language": "es"
}

Response (200 OK)

{
  "success": true,
  "original_text": "Hello, how are you?",
  "translated_text": "Hola, ¿cómo estás?",
  "source_language": "en",
  "target_language": "es",
  "cost_incurred": 0.0015
}

Payload Descriptions

textRequired
The raw text string you want to translate.
source_languageOptional
ISO code (e.g., 'en'). If omitted, the API will attempt to auto-detect the language.
target_languageRequired
ISO code of the language you want to translate the text into.

Translate Speech (Speech to Speech)

POST

/api/v1/translation/speech/sts/

Accepts base64 encoded audio and returns translated synthesized audio using Voice Cloning.

Request Payload

{
  "audio_base64": "UklGRiQAAABXQVZFZm10IBAAAA...",
  "source_language": "auto",
  "target_language": "fr"
}

Response (200 OK)

{
  "success": true,
  "audio_url": "https://cdn.letecho.com/...",
  "transcript": "Hello world",
  "translation": "Bonjour le monde",
  "cost_incurred": 0.08
}

Payload Descriptions

audio_base64Required
The base64 encoded audio string representing the source audio file.
source_languageOptional
ISO code. If 'auto' or omitted, the API will auto-detect the spoken language.
target_languageRequired
ISO code of the language you want to translate the speech into.

Transcribe Speech (Speech to Text)

POST

/api/v1/translation/speech/stt/

Accepts an audio file and returns the translated text transcription.

Request (Multipart/form-data)

audio_file: <File.mp3>
source_language: "es"
target_language: "en"

Response (200 OK)

{
  "success": true,
  "original_text": "Buenos días",
  "translated_text": "Good morning",
  "cost_incurred": 0.03
}

Payload Descriptions

audio_fileRequired
The raw audio file uploaded via Multipart/form-data.
source_languageOptional
ISO code. If omitted, the API will attempt to auto-detect the spoken language.
target_languageRequired
ISO code of the language you want to transcribe the speech into.

Synthesize Speech (Text to Speech)

POST

/api/v1/translation/speech/tts/

Accepts text payload and synthesizes high-quality audio in the target language.

Request Payload

{
  "text": "The weather is nice today.",
  "target_language": "de",
  "voice_id": "echo_neutral_01"
}

Response (200 OK)

{
  "success": true,
  "audio_url": "https://cdn.letecho.com/...",
  "duration_seconds": 3.4,
  "cost_incurred": 0.005
}

Payload Descriptions

textRequired
The text you want to synthesize into speech.
target_languageRequired
ISO code of the language to synthesize.
voice_idOptional
Specific voice model identifier (e.g., 'echo_neutral_01').

Common Error Responses

Validation Error (400)

{
  "success": false,
  "error": "Missing required field: target_language"
}

Insufficient Balance (402)

{
  "success": false,
  "error": "Insufficient wallet balance. Please recharge to continue using the API."
}

Document Processing (Async)

Asynchronous Translation

For large documents (PDF, DOCX, DOC, CSV, XLSX, XLS) or lengthy media files, processing cannot happen instantly. These requests are handled asynchronously. You submit the document, receive a job ID immediately, and ECHO fires a Webhook to your server when the translation is complete.

Translate Document

POST

/api/v1/translation/document/

Request (Multipart/form-data)

document: <File.pdf>
source_language: "auto"
target_language: "fr"
webhook_url: "https://your-domain.com/webhook"

Response (202 Accepted)

{
  "success": true,
  "job_id": "doc_8f73b2a9c1",
  "status": "processing",
  "message": "Document accepted. Webhook will be fired upon completion."
}

Payload Descriptions

documentRequired
The file to be translated. Accepted formats: .pdf .docx .doc .csv .xlsx .xls. Uploaded via multipart/form-data.
target_languageRequired
ISO 639-1 code of the target language.
webhook_urlRequired
URL to receive the translated payload when processing is completed asynchronously.
source_languageOptional
Original language ISO code. Defaults to "auto" for auto-detection.

Supported File Types

Only the formats listed below are accepted. Requests with any other file type will be rejected with a 400 error.

Documents

Document Translation API

.pdf

PDF

Text-based and scanned PDFs

.docx

Word (DOCX)

Microsoft Word 2007+

.doc

Word (DOC)

Microsoft Word legacy

.csv

CSV

Comma-separated values — text cells only

.xlsx

Excel (XLSX)

Excel 2007+ workbook

.xls

Excel (XLS)

Excel legacy workbook

Audio

Speech APIs

.wav

WAV

Lossless — best quality

.mp3

MP3

Most common compressed format

.mp4

MP4

Audio stream extracted from video

.webm

WebM

Browser-recorded audio

.opus

Opus

Low-latency compressed audio

.ogg

OGG

Open container format

CSV & Excel note: Only cells containing natural-language text are translated. Numeric values, dates, and formulas are preserved as-is.

Webhooks & Security

Long-running document tasks notify your server upon completion via Webhooks. ECHO signs webhook events so you can verify they originated securely from us.

1. Signature Verification

We include an X-Echo-Signature header with every webhook payload. The signature is an HMAC SHA-256 hash of the raw request body using your Client Secret as the key. Always verify this signature to prevent replay attacks and spoofing.

Node.js

import crypto from 'crypto';

const verifyWebhook = (reqBody, signature, secret) => {
  const hash = crypto.createHmac('sha256', secret)
                     .update(reqBody)
                     .digest('hex');
  return hash === signature;
};

Python

import hmac
import hashlib

def verify_webhook(req_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        req_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

2. Webhook Event Payload

When the document processing completes, ECHO sends a POST request to your specified `webhook_url` containing the final file location. Your endpoint must respond with a `200 OK`.

{
  "event_type": "document.translation.completed",
  "job_id": "doc_8f73b2a9c1",
  "data": {
    "status": "success",
    "document_type": "t2t",
    "source_language": "en",
    "target_language": "fr",
    "original_file_name": "report.pdf",
    "translated_file_url": "https://cdn.letecho.com/docs/translated_report.pdf",
    "cost_incurred": 0.45
  },
  "created_at": "2026-06-14T21:15:00Z"
}

Payload Structure

event_type

Identifies the type of webhook. E.g., document.translation.completed, audio.translation.completed, or *.failed.

data.document_type

The type of translation performed. Options: t2t, s2s, t2s, s2t.

data.translated_file_url

The secure URL to download the translated document or audio. Expires in 24 hours.