Lahajati AI - توثيق واجهة برمجة التطبيقات

مقدمة

مرحبًا بك في توثيق واجهة برمجة التطبيقات (API) الخاصة بـ Lahajati AI. ستجد هنا جميع المعلومات التي تحتاجها لدمج تقنية تحويل النص إلى كلام، تحويل الصوت إلى صوت، واستنساخ الأصوات المتطورة لدينا في تطبيقاتك.

إجراء الطلبات

المصادقة

تستخدم Lahajati AI API مفاتيح API للمصادقة على الطلبات. يمكنك الحصول على مفتاح API الخاص بك من لوحة تحكم حسابك.

يجب أن تتضمن جميع طلبات API مفتاح API الخاص بك في ترويسة Authorization:

Authorization: Bearer YOUR_API_KEY

الطلبات التي لا تحتوي على مصادقة ستفشل مع رمز الحالة `401 Unauthorized`.

معالجة الأخطاء (عام)

تستخدم واجهة برمجة تطبيقات لهجاتي رموز حالة HTTP القياسية للإشارة إلى نجاح أو فشل طلب API. بشكل عام: الرموز في نطاق `2xx` تشير إلى النجاح. الرموز في نطاق `4xx` تشير إلى خطأ ناتج عن المعلومات المقدمة من العميل (على سبيل المثال، معلمة مطلوبة مفقودة، فشل المصادقة، إلخ). الرموز في نطاق `5xx` تشير إلى خطأ من جانب خوادمنا.

`400 Bad Request`: لم يتمكن الخادم من فهم الطلب بسبب صياغة غير صالحة. تحقق من تنسيق جسم الطلب أو معلمات الاستعلام.
`401 Unauthorized`: مفتاح API الخاص بك مفقود، غير صالح، أو منتهي الصلاحية. تأكد من تضمين ترويسة `Authorization: Bearer YOUR_API_KEY` صالحة.
`403 Forbidden`: ليس لديك الإذن للوصول إلى هذا المورد أو تنفيذ هذه العملية (على سبيل المثال، محاولة تعديل مورد لا تملكه، أو تجاوز حدود الباقة).
`404 Not Found`: لم يتم العثور على المورد المطلوب (على سبيل المثال، `id_voice` غير موجود).
`422 Unprocessable Entity`: كان الطلب جيد الصياغة ولكن تعذر متابعته بسبب أخطاء دلالية (فشل التحقق من صحة الإدخال). سيتضمن جسم الاستجابة عادةً كائن `errors` مع تفاصيل الحقول التي فشلت في التحقق.
`429 Too Many Requests`: لقد تجاوزت حد معدل الطلبات (RPM) المسموح به لباقة اشتراكك. حاول مرة أخرى لاحقًا. راجع قسم حدود معدل الطلبات.
`500 Internal Server Error` / `502 Bad Gateway` / `503 Service Unavailable`: حدث خطأ غير متوقع من جانب الخادم أو أن الخدمة غير متاحة مؤقتًا. إذا استمرت المشكلة، يرجى الاتصال بالدعم.

حدود معدل الطلبات (RPM)

واجهة برمجة تطبيقات لهجاتي AI تفرض حدودًا على عدد الطلبات التي يمكن إجراؤها في الدقيقة (RPM) بناءً على باقة اشتراكك. تهدف هذه الحدود إلى ضمان أداء مستقر وعادل لجميع المستخدمين. تجاوز هذه الحدود سيؤدي إلى استجابة خطأ `429 Too Many Requests`.

الباقة	الطلبات في الدقيقة (RPM)
باقة البداية	100
باقة صانع المحتوى	250
الباقة المتميزة	400
باقة الأعمال	500

ملاحظة هامة: لطلب حدود أعلى لـ rpm لحزمة الأعمال، يرجى الاتصال بالدعم على: support@lahajati.ai.

حدود الطلبات المتزامنة

بالإضافة إلى حدود RPM، هناك قيود على عدد الطلبات المتزامنة التي يمكن لحسابك تشغيلها في نفس الوقت. هذا يساعد في الحفاظ على استقرار النظام.

الباقة	الحد الأقصى للطلبات المتزامنة
باقة البداية	5
باقة صانع المحتوى	10
الباقة المتميزة	15
باقة الأعمال	20

ملاحظة هامة: لطلب حدود تزامن أعلى لباقة الأعمال، يرجى التواصل مع الدعم عبر: support@lahajati.ai.

التحكم المطلق في توليد الكلام

توفر نقاط النهاية هذه تحكمًا دقيقًا ومتقدمًا في عملية توليد الكلام. يمكنك تحديد اللهجة وأسلوب الأداء بشكل منفصل أو توفير توجيهات نصية مخصصة (prompt) للحصول على المخرجات الصوتية المطلوبة بدقة.

GETGET الحصول على أصوات التحكم المطلق

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

يجلب قائمة بالأصوات المتاحة خصيصًا للاستخدام مع نقطة نهاية "توليد الكلام بالتحكم المطلق".

معلمات الاستعلام (Query Parameters)

معلمات اختيارية لفلترة النتائج وفرزها وتقسيمها إلى صفحات.

المعلمة	النوع	مطلوب	الوصف
`page`	integer (عدد صحيح)	لا (الافتراضي 1)	رقم الصفحة المطلوب من النتائج.
`per_page`	integer (عدد صحيح)	لا (الافتراضي 15، الأقصى 100)	عدد الأصوات التي يتم إرجاعها في كل صفحة.
`gender`	string (نص)	لا	فلترة حسب الجنس. القيم المسموح بها: `1` (ذكر)، `2` (أنثى)، `3` (أطفال).

الاستجابة الناجحة (200 OK)

إرجاع قائمة مقسمة إلى صفحات لكائنات الأصوات المتوافقة.

GETGET الحصول على أنماط الأداء

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

يجلب قائمة بأنماط الأداء المتاحة (مثل درامي، إخباري، إعلاني) التي يمكن استخدامها لتوجيه نموذج توليد الكلام.

معلمات الاستعلام (Query Parameters)

المعلمة	النوع	مطلوب	الوصف
`page`	integer (عدد صحيح)	لا (الافتراضي 1)	رقم الصفحة المطلوب من النتائج.
`per_page`	integer (عدد صحيح)	لا (الافتراضي 15، الأقصى 100)	عدد الأصوات التي يتم إرجاعها في كل صفحة.

الاستجابة الناجحة (200 OK)

إرجاع قائمة مقسمة إلى صفحات لكائنات أنماط الأداء.

GETGET الحصول على اللهجات

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

يجلب قائمة باللهجات المتاحة (مثل المصرية، السعودية النجدية) التي يمكن استخدامها لتوجيه نموذج توليد الكلام.

معلمات الاستعلام (Query Parameters)

المعلمة	النوع	مطلوب	الوصف
`page`	integer (عدد صحيح)	لا (الافتراضي 1)	رقم الصفحة المطلوب من النتائج.
`per_page`	integer (عدد صحيح)	لا (الافتراضي 15، الأقصى 100)	عدد الأصوات التي يتم إرجاعها في كل صفحة.

الاستجابة الناجحة (200 OK)

إرجاع قائمة مقسمة إلى صفحات لكائنات اللهجات.

POSTPOST توليد الكلام بالتحكم المطلق

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

يولد كلامًا من نص باستخدام صوت محدد وتحكم دقيق في الأداء عبر وضعين: الوضع المنظم (باستخدام معرفات الأداء واللهجة) أو وضع التوجيه المخصص.

فهم معلمة `input_mode`

هذه المعلمة هي مفتاح التحكم في هذه النقطة. لديها وضعان:

الوضع `0` (المنظم): في هذا الوضع، تقوم بتمرير `performance_id` و/أو `dialect_id` (اختياريان). سيقوم النظام بإنشاء التوجيه المناسب للذكاء الاصطناعي بناءً على اختياراتك. هذا هو الخيار الموصى به لمعظم حالات الاستخدام.
الوضع `1` (المخصص): في هذا الوضع، يتم تجاهل `performance_id` و `dialect_id`. بدلاً من ذلك، تقوم بتمرير توجيه نصي حر ومفصل في `custom_prompt_text`، مما يمنحك تحكمًا كاملاً. مثال: "تحدث ببطء وبهدوء، مع وقفات بين الجمل، كأنك تروي قصة أطفال.".

معلمات جسم الطلب (Request Body - JSON)

المعلمة	النوع	مطلوب	الوصف
`text`	string (نص)	نعم	النص المراد تحويله إلى كلام.
`id_voice`	string (معرف)	نعم	GET الحصول على أصوات التحكم المطلق: المعرف الفريد لمؤدي الصوت المطلوب. يمكن الحصول عليه عبر نقطة النهاية الحصول على الأصوات.
`input_mode`	string ("0" or "1")	نعم	يحدد وضع التحكم. `0` للوضع المنظم (باستخدام معرفات)، `1` لوضع التوجيه المخصص.
`performance_id`	string (معرف)	لا (مطلوب إذا كان `input_mode` هو `0`)	معرف نمط الأداء. يتم الحصول عليه من نقطة نهاية الحصول على أنماط الأداء.
`dialect_id`	string (معرف)	لا (مطلوب إذا كان `input_mode` هو `0`)	معرف اللهجة. يتم الحصول عليه من نقطة نهاية الحصول على اللهجات.
`custom_prompt_text`	string (نص)	لا (مطلوب إذا كان `input_mode` هو `1`)	توجيه نصي مخصص ومفصل لوصف الأداء المطلوب.

الاستجابة الناجحة

عند النجاح (`200 OK`)، سيحتوي جسم الاستجابة على بيانات الصوت الخام. ترويسة `Content-Type` ستكون `audio/mpeg`.

استجابات الخطأ

بالإضافة إلى الأخطاء العامة، قد تواجه الأخطاء التالية الخاصة بهذه النقطة:

401 ليس لديك الإذن أو الباقة اللازمة لاستخدام هذا الصوت.
401 رصيد نقاطك غير كافٍ لإتمام عملية توليد الصوت.
404 المعرف `id_voice` المحدد غير موجود.
422 فشل التحقق من صحة الإدخال. تأكد من أن المعلمات المطلوبة لكل `input_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

مثال على وضع التوجيه المخصص (`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

مثال على الوضع المنظم (`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());
}

مثال على وضع التوجيه المخصص (`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());
}

مثال على الوضع المنظم (`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));

مثال على وضع التوجيه المخصص (`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));

مثال على الوضع المنظم (`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.")

مثال على وضع التوجيه المخصص (`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.")

أمثلة الاستجابة

الاستجابة الناجحة (200 OK)

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

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

فشل التحقق من صحة الإدخال. تأكد من أن المعلمات المطلوبة لكل `input_mode` موجودة.

{
    "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."
        ]
    }
}

الحصول على أصوات التحكم المطلق

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

أمثلة الاستجابة

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

الحصول على أنماط الأداء

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

أمثلة الاستجابة

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

الحصول على اللهجات

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

أمثلة الاستجابة

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