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) |
---|---|
Free Package | 60 |
Starter Package | 300 |
Content Creator Package | 500 |
Premium Package | 800 |
Business Package | 1000 |
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 |
---|---|
Free Package | 2 |
Starter Package | 5 |
Content Creator Package | 50 |
Premium Package | 200 |
Business Package | 400 |
POSTPOST Text To Speech Super
https://lahajati.ai/api/v1/text-to-speech-pro
Generates high-quality speech audio from the provided text using the specified voice model and parameters.
Request Body Parameters (JSON)
Parameter | Type | Required | Description |
---|---|---|---|
text |
string | Yes | The text to be converted into speech. |
id_voice |
string | Yes | The unique identifier for the desired voice speaker. Obtainable via the Get Voices endpoint. |
privacy |
boolean (Boolean) | No (default `0`) | Set to `1` for more privacy (when set to 1, the transformation is treated as anonymous and the operation is never saved in our ruleset) |
professional_quality |
boolean | No (defaults to `0`) | Set to `1` to enable enhanced processing for professional-grade audio output. |
speech_speed |
float | No (defaults to `1.0`) | Controls the speed of the generated speech. Range: `0.8` to `1.3`. |
volume |
float | No (defaults to `1.0`) | Adjusts the volume of the generated speech. Range: `0.0` to `1.0`. |
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:
- 400 Invalid input format or missing required parameters.
- 404 The specified `id_voice` does not exist.
- 422 Input validation failed. The response body will contain details.
POSTPOST Speech To Speech Pro
https://lahajati.ai/api/v1/speech-to-speech-pro
Converts an audio file into speech using another specified voice, preserving intonation and style, using the specified voice model and parameters.
Note: When using `FormData` in JavaScript or equivalent in other libraries, the browser/library automatically sets the `Content-Type: multipart/form-data` header with the correct `boundary`. Do not set it manually.
Request Parameters (Form Data)
Parameter | Type | Required | Description |
---|---|---|---|
audio_file |
file (audio) | Yes | The audio file to convert. Supported types: `mp3, wav, aac, ogg`. Max size: 50MB. |
id_voice |
string | Yes | The unique identifier for the desired voice speaker. Obtainable via the Get Voices endpoint. |
professional_quality |
boolean | No (defaults to `0`) | Set to `1` to enable enhanced processing for professional-grade audio output. |
Success Response
On success (`200 OK`), the response body will contain the raw converted 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:
- 400 Invalid request, usually due to missing `audio_file` or incorrect `Content-Type`.
- 402 Insufficient points balance.
- 403 API key expired or insufficient permissions for the selected voice.
- 404 The specified `id_voice` does not exist.
- 422 Input validation failed. The response body will contain details.
GETGET Get Voices
https://lahajati.ai/api/v1/voices
Retrieves a list of available voices that can be used with the Text-to-Speech and Speech-to-Speech endpoints, including cloned voices.
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 voice objects matching the criteria.
Error Responses
In addition to the general errors, you might encounter the following endpoint-specific errors:
- 422 Query parameter validation failed. See `errors` object.
Voice Cloning Best Practices
To achieve the best results when using the voice cloning feature, providing high-quality audio samples is crucial. Below are guidelines and recommendations to help you prepare your audio files:
Audio Quality Guidelines
- Single Speaker Only: Ensure the recording clearly contains the voice of only one person (no other voices or background music).
- Consistent Performance: Maintain as consistent a volume, tone, and emotion as possible throughout the recording.
- Natural Pauses: Include short, natural pauses between sentences (0.5s is recommended).
- Quiet Environment: Record in a space as free from background noise and echo as possible.
- Professional Quality (Ideal): If possible, use professional recording equipment (good microphone) and an acoustically treated environment (minimize room echo).
Ideal Audio Sample Characteristics
- Recommended Duration: For optimal quality and performance versatility (e.g., ability to express different emotions), provide an audio sample longer than 60 seconds.
- For Consistent Performance: If targeting a specific, consistent performance style (like news reading), a 30 to 50-second sample with clear audio and steady delivery may suffice.
- Clarity and Purity: The audio sample must be completely free of noise and distortion (avoid audio clipping or distortion). Clear, clean audio is key.
- Intelligent Training: Our AI system will analyze and train itself on the voice's accent, tone, and performance style (whether happy, energetic, formal, etc.) from the provided sample.
Supported File Formats
We accept a variety of audio file formats (as specified in the `audio_file` parameter for the Create Cloned Voice endpoint).
POSTPOST Create Cloned Voice
https://lahajati.ai/api/v1/voices/cloned
Allows creating a new cloned voice by uploading a training audio file and providing necessary metadata. The cloned voice will be available for use in Text-to-Speech after processing is complete.
Note: When using `FormData` in JavaScript or equivalent in other libraries, the browser/library automatically sets the `Content-Type: multipart/form-data` header with the correct `boundary`. Do not set it manually.
Request Parameters (Form Data)
Parameter | Type | Required | Description |
---|---|---|---|
voice_name |
string | Yes | The name to give to the cloned voice. (Max: 25 characters). |
gender |
integer | Yes | Gender of the voice. Allowed values: `1` (Male), `2` (Female), `3` (Child). |
audio_file |
file (audio) | Yes | A single audio file for training the voice clone. Supported types: `mp3, wav, aac, ogg, flac, m4a`. Max size: 50MB. (Good quality, clear audio without background noise yields best results). |
enhance_audio |
boolean | No (defaults to `false`) | Set to `true` to enhance the quality of the training audio file before sending it to the cloning model (may increase processing time). |
voice_image |
file (image) | No | Image for the cloned voice. Supported types: `jpeg, png, jpg, gif, webp`. Max size: 2MB. |
voice_tags |
string | No | Optional comma-separated tags or categories for the cloned voice (e.g., "calm, formal"). (Max: 255 characters). |
preview_audio_sample |
file (audio) | No | Optional audio file as a sample to preview the cloned voice. Supported types: `mp3, wav`. Max size: 10MB. (Only available for certain user ranks). |
Success Response (201 Created)
On successful creation, returns the details of the newly created cloned voice. The voice may take some time to become fully active.
Error Responses (Create Cloned Voice)
In addition to the general errors, you might encounter the following endpoint-specific errors:
- 403 Maximum cloned voice limit reached.
- 422 Input validation failed (e.g., missing name, invalid file type, file too large).
- 500 Error communicating with the external voice cloning service or processing failed there.
PUTPUT Update Cloned Voice
https://lahajati.ai/api/v1/voices/cloned/{id_voice}
Allows updating the metadata of an existing cloned voice (e.g., name, gender, image, tags). The original training audio cannot be changed.
Path Parameter
Parameter | Type | Required | Description |
---|---|---|---|
{id_voice} |
string | Yes | The unique ID of the cloned voice to update (starts with `lvc_`). Passed as part of the URL. |
Optional Request Parameters (Form Data / JSON)
Parameter | Type | Required | Description |
---|---|---|---|
voice_name |
string | No | The name to give to the cloned voice. (Max: 25 characters). |
gender |
integer | No | Gender of the voice. Allowed values: `1` (Male), `2` (Female), `3` (Child). |
voice_image |
file (image) | No | Image for the cloned voice. Supported types: `jpeg, png, jpg, gif, webp`. Max size: 2MB. |
voice_tags |
string | No | Optional comma-separated tags or categories for the cloned voice (e.g., "calm, formal"). (Max: 255 characters). |
Success Response (200 OK)
On successful update, returns the updated cloned voice details.
Error Responses (Update Cloned Voice)
In addition to the general errors, you might encounter the following endpoint-specific errors:
- 404 Cloned voice not found, or you do not have permission to edit it.
- 422 Input validation failed (e.g., missing name, invalid file type, file too large).
DELETEDELETE Delete Cloned Voice
https://lahajati.ai/api/v1/voices/cloned/{id_voice}
Permanently deletes a cloned voice from the system and any associated external services.
Path Parameter
Parameter | Type | Required | Description |
---|---|---|---|
{id_voice} |
string | Yes | The unique ID of the cloned voice to update (starts with `lvc_`). Passed as part of the URL. |
Success Response (200 OK)
Confirmation message of successful deletion.
Error Responses (Delete Cloned Voice)
In addition to the general errors, you might encounter the following endpoint-specific errors:
- 404 Cloned voice not found, or you do not have permission to edit it.
- 500 Failed to delete the cloned voice (could be an issue with an external service).
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.