API Reference

Technical documentation for integrating the Zemen Amharic TTS engine. Our RESTful API relies on standard HTTP methods and JSON payloads.

Production Base URL https://amharic-tts.zai.et

1. Authentication

All requests to production endpoints require an API Key passed via the Authorization header as a Bearer token. Your API key should be kept secure and never exposed in client-side code.

Header	Requirement	Description
Authorization	Required	Bearer token. Format: `Bearer zai_sk_...`
Content-Type	Required	Must be set to `application/json` for POSTs.
X-Zemen-Region	Optional	Preferred routing region (e.g., `addis-ababa`).

2. Core Endpoints

POST /api/v1/tts

Synchronously convert Amharic text to an audio stream for immediate inline playback. Returns raw audio bytes upon success.

Request Body Parameters

Parameter	Type	Description
text *	string	Amharic text payload (Max 5,000 characters).
voice_id	string	`am-ET-Standard-A` (Female), `am-ET-Standard-B` (Male).
slow	boolean	Reduces speech rate by 25%. Default: `false`.

Example Response

HTTP/1.1 200 OK
Content-Type: audio/mpeg
Content-Length: 45092
X-Zai-Cache: HIT

[Binary Audio Data Stream]

3. Batch Processing

POST /api/v1/tts/batch

Submit an array of text payloads for asynchronous background processing. Highly recommended for generating large audio libraries or processing long-form documents. A webhook is triggered upon completion.

{
  "items": [
    { "id": "msg_001", "text": "የመጀመሪያ መልእክት" },
    { "id": "msg_002", "text": "ሁለተኛ መልእክት", "voice_id": "am-ET-Standard-B" }
  ],
  "webhook_url": "https://your-domain.com/zai/webhook"
}

4. Telemetry & Health

GET /api/v1/health

Check API status, current latency, and supported language configurations. Does not require authentication.

{
  "status": "operational",
  "version": "1.4.2",
  "region": "addis-ababa-1",
  "average_latency_ms": 115
}

5. Error Codes

Zemen APIs follow standard HTTP response codes and return detailed JSON error bodies.

Status	Code Name	Resolution
400	invalid_request_error	Ensure the payload matches the schema.
401	authentication_error	Provide a valid Bearer token.
429	rate_limit_exceeded	Back off requests. Check `X-RateLimit-Reset` header.

Contents