إرسال حدث

المعاملات

Lingara-Versionheaderstringاختياري

إصدار API الذي يُجاب عن هذا الطلب به. بدونه، يحصل رمز الوصول على الإصدار الذي رُبط به عميله، ويحصل الطلب الذي لا رمز مميز فيه على الإصدار الحالي. لا يمكن الوصول إلى الإصدار الذي لا يزال قيد التطوير إلا بذكره هنا. الإصدار غير المعروف يُجاب عنه بـ 400 مع الرمز api_version_unknown. يسرد GET /v1/versions الإصدارات.

Idempotency-Keyheaderstringمطلوب

قيمة تختارها لكل حدث وتعيد استخدامها عند إعادة المحاولة: من 1 إلى 255 حرف ASCII مرئيًا، مثل UUID. تحصل إعادة المحاولة بالمفتاح نفسه على الإجابة الأولى ولا تُفوتَر مرة أخرى، حتى لو اختلف محتواها. وبدون مفتاح صالح يُجاب الطلب بـ 400 مع الرمز idempotency_key_required.

متن الطلب application/json

typestringمطلوب

dataWorldPracticeRequestedمطلوب

topicstringمطلوب

source_langstringمطلوب

target_langstringمطلوب

levelintegerمطلوب

tagsarray of stringاختياري

generateboolean | nullاختياري

الاستجابات

202 تم تسجيل الحدث

idstringمطلوب

typestringمطلوب

created_atstringمطلوب

reactionReactionReport | nullاختياري

statusReactionStatusمطلوب

plan_idstring | nullاختياري

plan_statusPlanStatus | nullاختياري

حالة الخطة عند قبول الحدث. وحدها generating تَعِد بأن lesson_plan.ready أو lesson_plan.failed سيتبع. وأي قيمة أخرى تعني خطة مقدَّمة من المكتبة، يمكنك قراءتها الآن عبر GET /v1/lesson-plans/{id}.

codestring | nullاختياري

errorstring | nullاختياري

الأخطاء

402application/json

رُفض استدعاء عميل يُفوتَر بحسب الاستهلاك قبل أن يُنفق أي شيء. spend_cap_reached: بلغ العميل أو حسابه حدّ الإنفاق الشهري؛ ارفع الحد في صفحة عمليات التكامل. metered_billing_inactive: الفوترة بحسب الاستهلاك غير مفعّلة لهذا الحساب؛ فعّلها أو حدّث طريقة الدفع في صفحة عمليات التكامل.

410application/json

تم إيقاف إصدار API الذي يُجاب عن هذا الطلب به. أرسل إصدارًا مدعومًا في Lingara-Version، أو اربط العميل بإصدار آخر.

4XXapplication/json

رُفض الطلب. يوضّح code السبب، ويشرحه error بالكلمات.

503application/json · text/plain

الخدمة غير متاحة مؤقتًا؛ أعد المحاولة بعد عدد الثواني المذكور في Retry-After. أثناء الصيانة يكون المتن نصًا عاديًا بدلًا من غلاف الخطأ.

5XXapplication/json

رُفض الطلب. يوضّح code السبب، ويشرحه error بالكلمات.

codestringمطلوب

سبب رفض الطلب، في صورة رمز ثابت يمكن التفرّع بناءً عليه: مثل insufficient_scope (403) وrate_limited (429)، ولعميل يُفوتَر بحسب الاستهلاك spend_cap_reached (402) وmetered_billing_inactive (402).

errorstringمطلوب

مثال

curl -X POST "https://api.getlingara.com/v1/events" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"world.context_changed","data":{"scene":"A night market in Taipei, just after rain","npc":{"name":"Auntie Lin","persona":"a street-food vendor who likes to haggle"},"source_lang":"en","target_lang":"zh","level":3,"tags":["market","food","chapter-2"],"generate":true}}'

تفضّل مكتبة؟ راجع قسم المكتبات.