Lahajati AI API Documentation

Introduction

Welcome to the Lahajati AI API documentation. Here you will find all the information you need to integrate our cutting-edge text-to-speech, speech-to-speech, and voice cloning technology into your applications.

Making Requests

Authentication

Lahajati AI API uses API keys to authenticate requests. You can obtain your API key from your account dashboard.

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Requests without authentication will fail with a `401 Unauthorized` status code.

Error Handling (General)

Lahajati AI API uses standard HTTP status codes to indicate the success or failure of an API request. In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided by the client (e.g., a required parameter was omitted, authentication failed, etc.). Codes in the `5xx` range indicate an error with our servers.

`400 Bad Request`: The server could not understand the request due to invalid syntax. Check your request body format or query parameters.
`401 Unauthorized`: Your API key is missing, invalid, or expired. Ensure you're including a valid `Authorization: Bearer YOUR_API_KEY` header.
`403 Forbidden`: You do not have permission to access this resource or perform this action (e.g., trying to modify a resource you don't own, or package limits exceeded).
`404 Not Found`: The requested resource could not be found (e.g., a non-existent `id_voice`).
`422 Unprocessable Entity`: The request was well-formed but was unable to be followed due to semantic errors (input validation failed). The response body will typically include an `errors` object with details on which fields failed validation.
`429 Too Many Requests`: You've exceeded the request rate limit (RPM) allowed for your subscription package. Try again later. See the Rate Limits section.
`500 Internal Server Error` / `502 Bad Gateway` / `503 Service Unavailable`: An unexpected error occurred on our server side, or the service is temporarily unavailable. If the problem persists, please contact support.

Rate Limits (RPM)

Lahajati AI API enforces limits on the number of requests you can make per minute (RPM) based on your subscription package. These limits are in place to ensure stable and fair performance for all users. Exceeding these limits will result in a `429 Too Many Requests` error response.

Package	Requests Per Minute (RPM)
Starter Package	100
Content Creator Package	250
Premium Package	400
Business Package	500

Important Note: To request higher rpm limits for the Business package, please contact support at: support@lahajati.ai.

Concurrent Request Limits

In addition to RPM limits, there are restrictions on the number of concurrent requests your account can have running simultaneously. This helps maintain system stability.

Package	Max Concurrent Requests
Starter Package	5
Content Creator Package	10
Premium Package	15
Business Package	20

Important Note: To request higher concurrency limits for the Business package, please contact support at: support@lahajati.ai.

Absolute Control TTS

These endpoints provide granular, advanced control over the speech generation process. You can specify dialect and performance style separately or provide a custom text prompt to get precisely the audio output you need.

GETGET Get Absolute Control Voices

https://lahajati.ai/api/v1/voices-absolute-control

Retrieves a list of voices available specifically for use with the "Generate Speech with Absolute Control" endpoint.

Query Parameters

Optional parameters to filter, sort, and paginate the results.

Parameter	Type	Required	Description
`page`	integer	No (defaults to 1)	The page number of the results to retrieve.
`per_page`	integer	No (defaults to 15, max 100)	The number of voices to return per page.
`gender`	string	No	Filter by gender. Allowed values: `1` (Male), `2` (Female), `3` (Child).

Success Response (200 OK)

Returns a paginated list of compatible voice objects.

GETGET Get Performance Styles

https://lahajati.ai/api/v1/performance-absolute-control

Retrieves a list of available performance styles (e.g., dramatic, news-like, commercial) that can be used to guide the speech generation model.

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No (defaults to 1)	The page number of the results to retrieve.
`per_page`	integer	No (defaults to 15, max 100)	The number of voices to return per page.

Success Response (200 OK)

Returns a paginated list of performance style objects.

GETGET Get Dialects

https://lahajati.ai/api/v1/dialect-absolute-control

Retrieves a list of available dialects (e.g., Egyptian, Saudi Najdi) that can be used to guide the speech generation model.

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No (defaults to 1)	The page number of the results to retrieve.
`per_page`	integer	No (defaults to 15, max 100)	The number of voices to return per page.

Success Response (200 OK)

Returns a paginated list of dialect objects.

POSTPOST Generate Speech with Absolute Control

https://lahajati.ai/api/v1/text-to-speech-absolute-control

Generates speech from text using a specified voice and fine-grained performance control via two modes: Structured Mode (using performance and dialect IDs) or Custom Prompt Mode.

Understanding the `input_mode` Parameter

This parameter is key to controlling this endpoint. It has two modes:

Mode `0` (Structured): In this mode, you pass `performance_id` and/or `dialect_id` (both are optional). The system will construct the appropriate prompt for the AI based on your selections. This is the recommended option for most use cases.
Mode `1` (Custom): In this mode, `performance_id` and `dialect_id` are ignored. Instead, you pass a detailed, free-form text prompt in `custom_prompt_text`, giving you full control. E.g., "Speak slowly and calmly, with pauses between sentences, as if you are telling a children's story."

Request Body Parameters (JSON)

Parameter	Type	Required	Description
`text`	string	Yes	The text to be converted into speech.
`id_voice`	string	Yes	GET Get Absolute Control Voices: The unique identifier for the desired voice speaker. Obtainable via the Get Voices endpoint.
`input_mode`	string ("0" or "1")	Yes	Defines the control mode. `0` for Structured Mode (using IDs), `1` for Custom Prompt Mode.
`performance_id`	string (ID)	No (Required if `input_mode` is `0`)	The ID for the performance style. Obtained from the Get Performance Styles endpoint.
`dialect_id`	string (ID)	No (Required if `input_mode` is `0`)	The ID for the dialect. Obtained from the Get Dialects endpoint.
`custom_prompt_text`	string	No (Required if `input_mode` is `1`)	A custom, detailed text prompt describing the desired performance.

Success Response

On success (`200 OK`), the response body will contain the raw audio data. The `Content-Type` header will be `audio/mpeg`.

Error Responses

In addition to the general errors, you might encounter the following endpoint-specific errors:

401 You do not have the permission or package to use this voice.
401 Your points balance is not enough to perform the voice generation process.
404 The specified `id_voice` does not exist.
422 Input validation failed. Ensure the required parameters for each `input_mode` are present.

Generate Speech with Absolute Control

Example for Structured Mode (`input_mode: "0"`)

curl -X POST "https://lahajati.ai/api/v1/text-to-speech-absolute-control" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: audio/mpeg" \
-d '{
  "text": "هذا اختبار للوضع المنظم.",
  "id_voice": "ac_voice_xyz789",
  "input_mode": "0",
  "performance_id": "perf_1",
  "dialect_id": "dialect_10"
}' \
--output structured_output.mp3

Example for Custom Prompt Mode (`input_mode: "1"`)

curl -X POST "https://lahajati.ai/api/v1/text-to-speech-absolute-control" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: audio/mpeg" \
-d '{
  "text": "هذا اختبار للتوجيه المخصص.",
  "id_voice": "ac_voice_xyz789",
  "input_mode": "1",
  "custom_prompt_text": "اقرأ النص التالي بصوت عالٍ وواضح، كأنك تقدم نشرة إخبارية عاجلة."
}' \
--output custom_prompt_output.mp3

Example for Structured Mode (`input_mode: "0"`)

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

$response = Http::withToken('YOUR_API_KEY')
    ->accept('audio/mpeg')
    ->post('https://lahajati.ai/api/v1/text-to-speech-absolute-control', [
        'text'           => 'هذا اختبار للوضع المنظم.',
        'id_voice'       => 'ac_voice_xyz789',
        'input_mode'     => '0',
        'performance_id' => 'perf_1',
        'dialect_id'     => 'dialect_10'
    ]);

if ($response->successful()) {
    Storage::disk('public')->put('structured_output.mp3', $response->body());
}

Example for Custom Prompt Mode (`input_mode: "1"`)

$response = Http::withToken('YOUR_API_KEY')
    ->accept('audio/mpeg')
    ->post('https://lahajati.ai/api/v1/text-to-speech-absolute-control', [
        'text'               => 'هذا اختبار للتوجيه المخصص.',
        'id_voice'           => 'ac_voice_xyz789',
        'input_mode'         => '1',
        'custom_prompt_text' => 'اقرأ النص التالي بصوت عالٍ وواضح، كأنك تقدم نشرة إخبارية عاجلة.'
    ]);

if ($response->successful()) {
    Storage::disk('public')->put('custom_prompt_output.mp3', $response->body());
}

Example for Structured Mode (`input_mode: "0"`)

const structuredData = {
    text: "هذا اختبار للوضع المنظم.",
    id_voice: "ac_voice_xyz789",
    input_mode: "0",
    performance_id: "perf_1",
    dialect_id: "dialect_10"
};

fetch('https://lahajati.ai/api/v1/text-to-speech-absolute-control', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'audio/mpeg'
    },
    body: JSON.stringify(structuredData)
})
.then(response => response.blob())
.then(blob => console.log('Structured audio received!'))
.catch(error => console.error('Error:', error));

Example for Custom Prompt Mode (`input_mode: "1"`)

const customData = {
    text: "هذا اختبار للتوجيه المخصص.",
    id_voice: "ac_voice_xyz789",
    input_mode: "1",
    custom_prompt_text": "اقرأ النص التالي بصوت عالٍ وواضح، كأنك تقدم نشرة إخبارية عاجلة."
};

fetch('https://lahajati.ai/api/v1/text-to-speech-absolute-control', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'audio/mpeg'
    },
    body: JSON.stringify(customData)
})
.then(response => response.blob())
.then(blob => console.log('Custom prompt audio received!'))
.catch(error => console.error('Error:', error));

Example for Structured Mode (`input_mode: "0"`)

import requests

headers = {
    'Authorization': f'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'audio/mpeg'
}
structured_data = {
    "text": "هذا اختبار للوضع المنظم.",
    "id_voice": "ac_voice_xyz789",
    "input_mode": "0",
    "performance_id": "perf_1",
    "dialect_id": "dialect_10"
}
response = requests.post('https://lahajati.ai/api/v1/text-to-speech-absolute-control', headers=headers, json=structured_data)

if response.status_code == 200:
    with open('structured_output.mp3', 'wb') as f:
        f.write(response.content)
    print("Structured audio saved.")

Example for Custom Prompt Mode (`input_mode: "1"`)

custom_data = {
    "text": "هذا اختبار للتوجيه المخصص.",
    "id_voice": "ac_voice_xyz789",
    "input_mode": "1",
    "custom_prompt_text": "اقرأ النص التالي بصوت عالٍ وواضح، كأنك تقدم نشرة إخبارية عاجلة."
}
response = requests.post('https://lahajati.ai/api/v1/text-to-speech-absolute-control', headers=headers, json=custom_data)

if response.status_code == 200:
    with open('custom_prompt_output.mp3', 'wb') as f:
        f.write(response.content)
    print("Custom prompt audio saved.")

Response Examples

Success Response (200 OK)

HTTP/1.1 200 OK
Content-Type: audio/mpeg
Content-Length: 98765

[... raw binary audio data ...]

Input validation failed. Ensure the required parameters for each `input_mode` are present.

{
    "success": false,
    "errors": {
        "input_mode": [
            "The input mode field is required."
        ],
        "custom_prompt_text": [
            "The custom prompt text field is required when input mode is 1."
        ]
    }
}

Get Absolute Control Voices

curl -X GET "https://lahajati.ai/api/v1/voices-absolute-control" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

Response Examples

{
  "success": true,
  "data": [
    {
      "id_voice": "ac_voice_xyz789",
      "display_name": "صوت تحكم مطلق - أحمد",
      "gender": "male",
      "is_cloned": false,
      "average_rating": null
    }
  ],
  "meta": { /* ... pagination info ... */ }
}

Get Performance Styles

curl -X GET "https://lahajati.ai/api/v1/performance-absolute-control" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

Response Examples

{
  "success": true,
  "data": [
    {
      "performance_id": "perf_1",
      "display_name": "أداء درامي"
    },
    {
      "performance_id": "perf_2",
      "display_name": "أداء إخباري"
    }
  ],
  "meta": { /* ... pagination info ... */ }
}

Get Dialects

curl -X GET "https://lahajati.ai/api/v1/dialect-absolute-control" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

Response Examples

{
  "success": true,
  "data": [
    {
      "dialect_id": "dialect_10",
      "display_name": "اللهجة المصرية"
    },
    {
      "dialect_id": "dialect_12",
      "display_name": "اللهجة السعودية (نجدية)"
    }
  ],
  "meta": { /* ... pagination info ... */ }
}