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.

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.

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.

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.