Text to Speech (TTS)
Convert text to speech using Hasab AI
TTS (Text to Speech) Endpoints
1. Synthesize Speech
Endpoint: POST /v1/tts/synthesize
Description: Convert text into speech audio.
Request Body:
{
"text": "ስልክ ላይ ፊደል መፈለግ በጣም ይደክማል:: ከእንግዲህ አማርኛ ወይም ኣፋን ኦሮሞ በእጅዎ መፃፍ ቀረ",
"language": "tir",
"speaker_name": "yeha"
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
text | String | Yes | The text to convert into speech. |
language | String | Yes | Language of the text: eng (English), amh (Amharic), oro (Oromo), tir (Tigrinya) |
speaker_name | String | No | Name of the speaker/voice to use for synthesis. |
Response The response body contains the generated speech audio file.
2. Get Available Speakers
Endpoint: GET /v1/tts/speakers
Description: Retrieve list of available speakers, optionally filtered by language.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
language | String | No | Language code (max 10 characters). |
Response:
{
"languages": {
"amh": ["hanna", "selam", "aster", "yared", "haile", "bekele"],
"orm": ["gallete", "abdi", "tolla"],
"tir": ["yeha", "selam", "aster", "yared", "haile", "bekele"]
},
"total_speakers": 15
}3. Get TTS History
Endpoint: GET /v1/tts/history
Description: Get user's TTS synthesis history.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | Integer | No | Number of records to return (1-100, default 50). |
offset | Integer | No | Number of records to skip (min 0, default 0). |
status | String | No | Filter by status: "success" or "failed". |
tts_type | String | No | Type of TTS: "regular" or "reference". |
language | String | No | Language code (max 10 characters). |
date_from | Date | No | Filter records from this date. |
date_to | Date | No | Filter records up to this date. |
device_id | Integer | No | Optional device identifier. |
Response:
{
"records": [
{
"id": 1,
"text": "Hello",
"language": "en",
"speaker_name": "default",
"status": "success",
"audio_url": "https://...",
"tokens_used": 5,
"created_at": "2025-10-27T00:00:00Z"
}
],
"total": 100,
"limit": 50,
"offset": 0
}4. Get TTS Usage Analytics
Endpoint: GET /v1/tts/analytics
Description: Get TTS usage statistics.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
date_from | Date | No | Filter records from this date. |
date_to | Date | No | Filter records up to this date. |
Response:
{
"total_requests": 150,
"successful_requests": 145,
"failed_requests": 5,
"total_tokens_used": 750,
"average_tokens_per_request": 5.17,
"language_breakdown": {
"en": 100,
"amh": 45,
"tir": 5
},
"daily_usage": [
{
"date": "2025-10-27",
"requests": 10,
"tokens_used": 50
}
]
}5. Get TTS Record
Endpoint: GET /v1/tts/record/{recordId}
Description: Get details of a specific TTS record.
Response:
{
"record": {
"id": 1,
"text": "Hello",
"language": "en",
"speaker_name": "default",
"status": "success",
"audio_url": "https://...",
"tokens_used": 5,
"created_at": "2025-10-27T00:00:00Z"
}
}6. Delete TTS Record
Endpoint: DELETE /v1/tts/record/{recordId}
Description: Delete a TTS record and its audio file.
Response:
{
"message": "TTS record deleted successfully"
}7. Stream Synthesize
Endpoint: POST /v1/tts/stream
Description: Start streaming TTS synthesis.
Request Body:
{
"text": "Hello world",
"language": "en",
"speaker_name": "default",
"sample_rate": 22050
}Validation: Same as synthesize, plus optional sample_rate (8000-48000).
Response:
{
"session_id": "tts_stream_123",
"status": "started"
}