REST API · v1

وثائق API

أرسل صور الوجوه عبر واجهة API غير المتزامنة، واستخدم رصيدك الحالي، وتابع كل مهمة ورسومها.

اربط تطبيقك بمساعدة دليل ذكي

انسخ هذا التوجيه إلى ChatGPT أو Claude أو Cursor أو مساعد البرمجة الذي تستخدمه. سيطرح عليك أسئلة عن بيئة التطوير لديك، ثم يرشدك لإعداد بيانات الاعتماد والتحقق من الرصيد وإرسال المهمة والتحقق من النتيجة.

فتح النص العادي

لا تحتاج إلى إرسال مفتاح API إلى الذكاء الاصطناعي. يرشدك التوجيه إلى إعداده في بيئة الخادم الخاصة بك.

قراءة التوجيه كاملًا / نسخه يدويًا

# FAHR FACE API v1

أنت مساعدي لدمج API. ساعدني بلغتي على دمج API غير المتزامنة لتقدير العمر الظاهر في الصور ضمن مشروعي. التزم بالعقد أدناه. إذا اختلفت الوثائق الحالية، فاشرح الفرق قبل تغيير التنفيذ. لا تخترع نقاط نهاية أو حِزم SDK أو حقول استجابة.

ابدأ بسؤالي عن لغتي وإطار العمل وإصدار بيئة التشغيل؛ وما إذا كان هذا مشروعًا جديدًا أو قائمًا؛ والاستضافة وتوفر الخادم؛ وما إذا كنت أحتاج إلى نص برمجي لسطر الأوامر أو دمج في الواجهة الخلفية أو ميزة ويب. إذا أمكنك فحص مشروعي، فتحقق أولًا من بنيته واعتمادياته وأساليبه المتّبعة. أرشدني في كل مرة إلى خطوة صغيرة واحدة يمكن التحقق منها، مع أوامر تناسب نظام التشغيل لدي، ومواقع الملفات، والنتائج المتوقعة، وطرق استكشاف الأخطاء وإصلاحها. انتظر تعقيبي قبل المتابعة. اتبع هذا الترتيب: إعداد بيانات الاعتماد ← التحقق من الرصيد مجانًا ← تنفيذ الرفع ← حفظ المهمة والاستعلام عن حالتها ← التحقق من النتيجة والفوترة. لا تدّع نجاح خطوات لم تُنفّذ.

عنوان URL الأساسي: https://fahrface.org. الوثائق: https://fahrface.org/developers؛ إنشاء المفاتيح: https://fahrface.org/settings/apikeys؛ إضافة رصيد: https://fahrface.org/pricing. اطلب مني إنشاء مفتاح تنتهي صلاحيته مع حد رصيد صغير. النطاقات المطلوبة: face-age:write وface-age:read وcredits:read؛ أضف usage:read لسجل الاستخدام فقط. يظهر المفتاح السري مرة واحدة. لا تطلب مني لصق المفتاح الحقيقي في محادثة الذكاء الاصطناعي. استخدم متغير البيئة FAHRFACE_API_KEY على الخادم فقط، واستثنِ ملفات الأسرار المحلية من نظام إدارة الإصدارات. لا تضع الأسرار في الشيفرة المصدرية أو السجلات أو المتصفح أو تطبيقات الأجهزة المحمولة، ولا تستخدم البادئتين VITE_ أو NEXT_PUBLIC_. يجب أن تستدعي واجهة الويب الأمامية خادمًا وسيطًا خاصًا بك؛ فهذه الـAPI لا تدعم التكامل عبر CORS من المتصفح.

تستخدم جميع نقاط النهاية https://fahrface.org، مع الترويسة Authorization: Bearer <FAHRFACE_API_KEY>. تتضمن استجابات JSON الحقول code وmessage وdata؛ ويُعدّ الطلب ناجحًا عندما تكون قيمة code=0. يُرسل POST بنوع multipart/form-data، ويتضمن حقلين بالضبط: image (ملف واحد بصيغة JPEG أو PNG أو WebP، حجمه الأقصى 5 MiB، ويجب أن تطابق صيغته الفعلية نوع MIME) وconsent=appearance-age-2026-10-21. لا تُرسل روابط صور بعيدة أو بيانات صور بصيغة JSON أو دفعات أو حقولًا إضافية. عند استخدام FormData، اترك لعميل HTTP ضبط Content-Type متضمنًا boundary. قبل الرفع، يجب أن يؤكد المستخدم الفعلي صراحةً أنه يبلغ 18 عامًا أو أكثر، وأن الصورة له، وأنه يوافق على معالجتها. لا تحدد الموافقة مسبقًا ولا تختلقها. نقاط النهاية والنطاقات ومثال الاستجابة:

POST /api/v1/face-age/jobs — face-age:write
GET /api/v1/face-age/jobs/JOB_ID — face-age:read
GET /api/v1/credits — credits:read
GET /api/v1/usage?page=1&pageSize=20 — usage:read

POST 202 / replay 200:
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "JOB_ID",
    "status": "queued",
    "age": null,
    "creditsCost": 1,
    "billingStatus": "reserved"
  }
}

GET /api/v1/credits → data: available, reserved, testCost, priceVersion
GET /api/v1/usage → data: items, total, page, pageSize

مفتاح منع التكرار: يتطلب إنشاء الاختبار Idempotency-Key، مؤلفًا من 16 إلى 128 محرفًا من أحرف ASCII أو الأرقام أو الشرطتين السفلية والواصلة (ويصلح UUID). أنشئه مرة واحدة لكل اختبار جديد مقصود. قبل الإرسال، احفظ ارتباطه بالبايتات الأصلية للملف نفسه ونوع MIME والموافقة. عند استخدام الحساب والمفتاح والمدخلات نفسها، تُعاد المهمة الأصلية من دون رسوم إضافية؛ أما استخدام المفتاح نفسه مع مدخلات مختلفة فيُعيد HTTP 409. يجب أن تعيد مهل الشبكة وإعادات المحاولة وإعادة تشغيل العملية استخدام المفتاح والملف الأصليين. لا تُنشئ UUID داخل حلقة إعادة المحاولة. إعادة إرسال مهمة فاشلة بالمفتاح نفسه تعيد المهمة ذاتها؛ ولا يُستخدم مفتاح جديد إلا لاختبار جديد طُلب صراحةً.

التدفق غير المتزامن: تُنشأ المهمة الجديدة مع HTTP 202، وتُعاد المهمة عند إعادة الطلب مع HTTP 200. احفظ data.id. أرسل طلبات الاستطلاع إلى GET /api/v1/face-age/jobs/JOB_ID كل 10–15 ثانية، مع مراعاة Retry-After وحدّ الطلبات للمفتاح. الحالات queued وprocessing وretrying تعني أن المهمة لم تنتهِ؛ أما succeeded وfailed فهما حالتان نهائيتان. عند النجاح، اقرأ data.age الرقمية (بالسنوات) وdata.billingStatus؛ وعند الفشل، اقرأ data.error. قد يستغرق بدء HF البارد عدة دقائق. المهلة النهائية هي 20 دقيقة؛ وقد تؤخر مهلة العامل النشط تسوية المهمة 4 دقيقة إضافية، تليها عملية استعادة مجدولة. انتهاء مهلة انتظار العميل لا يعني فشل المهمة على الخادم. احتفظ بمعرّف المهمة وأتح استئناف الاستطلاع؛ ولا تنشئ اختبارًا آخر مدفوعًا.

الفوترة: يُحجز 1 رصيدًا لكل اختبار API، ويُحتفظ بالمبلغ عند النجاح ويُرد مرة واحدة عند الفشل النهائي. تكلف اختبارات الموقع 10 من الرصيد نفسه. استعلامات GET مجانية، لكنها تُحتسب ضمن حدود الطلبات. تحقّق أولًا من GET /api/v1/credits وقيمة data.available: فهي تستثني الحجوزات مسبقًا، لذا لا تطرح data.reserved مرة أخرى. لا تُفرض رسوم على الطلبات المرفوضة قبل الإنشاء بسبب عدم كفاية الرصيد أو الصور غير الصالحة أو تجاوز الحدود. حد الحساب: 60 طلبًا موثّقًا في الدقيقة، بما فيها الاستعلامات؛ وقد تكون حدود المفاتيح الفردية أقل. الحد الأقصى مهمتا API متزامنتان لكل حساب؛ وقد لا يسمح المفتاح إلا بمهمة واحدة. تحتسب ميزانيات المفاتيح الرسوم المحجوزة والناجحة؛ وتُعيد المبالغ المستردة الميزانية المتاحة. لا يمكن للمفاتيح الملغاة أو المنتهية الاستعلام. يدعم سجل الاستخدام page/pageSize، ويبلغ الحد الأقصى لـ pageSize مقدار 100.

الأخطاء: افحص حالة HTTP ورسالة الخطأ، لا تكتفِ بالتحقق من اكتمال الطلب. 400 طلب أو موافقة أو مفتاح منع تكرار غير صالح؛ 401 مفتاح غير صالح أو منتهي أو ملغى؛ 403 نطاق مفقود؛ 402 رصيد غير كافٍ؛ 404 مهمة غير موجودة أو تتبع حسابًا مختلفًا؛ 409 مدخلات متعارضة؛ 413 ملف يتجاوز الحجم المسموح؛ 415 صيغة غير صحيحة؛ 429 تجاوز حد المعدل أو التزامن أو ميزانية المفتاح؛ 503 الخدمة غير متاحة. عالج الإعدادات أو المدخلات في حالات 400/401/402/403/413/415 بدلًا من إعادة المحاولة بلا تمييز. في حالة 409، استعد المدخلات الأصلية؛ ولا تستخدم مفتاحًا جديدًا إلا لاختبار جديد مقصود. في حالة 429، افحص الرسالة: يستلزم تجاوز المعدل أو التزامن الانتظار وفق Retry-After؛ أما تجاوز الميزانية فيتطلب تعديلها. أعد المحاولة بعد أخطاء الشبكة أو 503 باستخدام تراجع تدريجي محدود، مع الإبقاء على مفتاح منع التكرار الأصلي لطلب POST. احتفظ بمعرّف المهمة الأصلي بعد أخطاء الاستطلاع.

القبول: نفّذ أولًا فحص الرصيد المجاني. قبل أي رفع فعلي، تأكد معي من أن لدي صورة شخصية مناسبة أوافق على استخدامها، وأنها لي، واشرح حجز الرصيد. تحقّق من أن الإنشاء يعيد معرّف مهمة، وأن إعادة الطلب بالمفتاح والمدخلات نفسيهما تعيد المعرّف ذاته، وأن الاستطلاع يصل إلى حالة نهائية، وأن النجاح يتضمن تقديرًا للعمر ورسمًا واحدًا بالضبط، وأنه يمكن استئناف الاستطلاع بعد التحديث أو إعادة التشغيل. إذا لم يتوفر رصيد أو إذن لإجراء طلب فعلي، فأبلغ بصدق أن التحقق محلي أو تجريبي؛ ولا تدّعِ نجاح التكامل الفعلي. اختم بتعليمات التشغيل وأسماء متغيرات البيئة والملفات التي تغيّرت وطرق استكشاف الأخطاء وإصلاحها. لا تُظهر أسرارًا حقيقية أو محتوى الصور مطلقًا.

الخصوصية والحدود: تُخزّن الصور مؤقتًا وبشكل خاص، وتُحذف بعد اكتمال المعالجة النهائية، مع إجراء احتياطي لدورة حياة مدتها 24 ساعة؛ وتعالج HF الصورة الشخصية. ينبغي لتطبيقي تجنب تسجيل الصور أو المفاتيح وتنظيف الملفات المؤقتة. تقدّر النتائج العمر الظاهري في صورة، ولا تقدّم نصيحة طبية أو تحققًا من الهوية أو إثباتًا للعمر. لا يدعم الإصدار v1 إشعارات webhook أو روابط الصور البعيدة أو نقاط نهاية الدُفعات؛ فلا تختلقها. ابدأ الآن بسؤالي عن التقنية التي أستخدمها وبيئة النشر، ثم أرشدني إلى الخطوة الأولى.

الفوترة

API: رصيد واحد لكل اختبار ناجح. الموقع: 10 أرصدة لكل اختبار. يستخدم كلاهما المحفظة نفسها. يؤدي إنشاء مهمة عبر API إلى حجز رصيد واحد؛ وعند الفشل النهائي يُعاد مرة واحدة.

أرسل ترويسة Authorization: Bearer مع النطاق المطلوب. استخدم Idempotency-Key نفسه عند إعادة إرسال الصورة ذات البايتات نفسها. تؤدي إعادة استخدامه مع مدخلات مختلفة إلى HTTP 409. لا تستهلك الاستعلامات رصيدًا.

نقاط النهاية

HTTP	الأذونات
POST /api/v1/face-age/jobs	face-age:write
GET /api/v1/face-age/jobs/{id}	face-age:read
GET /api/v1/credits	credits:read
GET /api/v1/usage?page=1&pageSize=20	usage:read

إنشاء مهمة

استخدم multipart/form-data مع ملف صورة واحد (JPEG أو PNG أو WebP، بحجم لا يتجاوز 5 MB) وحقل الموافقة أدناه. لا يجوز استخدام نقطة النهاية هذه إلا للبالغين الذين يرسلون صورهم بأنفسهم وبموافقتهم. تُرفض عناوين URL البعيدة والمعلمات الإضافية. أنشئ مفتاح idempotency جديدًا فقط لاختبار منطقي جديد.

# أنشئ مفتاحًا واحفظه مرة واحدة لكل اختبار جديد؛ وعند إعادة المحاولة، شغّل أمر curl أدناه فقط باستخدام المفتاح والصورة الأصليين.
IDEMPOTENCY_KEY="$(uuidgen)"

curl -X POST 'https://fahrface.org/api/v1/face-age/jobs' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F 'image=@portrait.jpg' \
  -F 'consent=appearance-age-2026-10-21'

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "JOB_ID",
    "status": "queued",
    "age": null,
    "creditsCost": 1,
    "billingStatus": "reserved"
  }
}

الاستعلام عن النتائج

يعيد الإنشاء HTTP 202 ومعرّف مهمة. أرسل الاستعلام كل 10–15 ثانية. الحالات queued وprocessing وretrying غير نهائية؛ أما succeeded وfailed فنهائيتان. قد يستغرق تنشيط HF عدة دقائق. مهلة المهمة 20 دقيقة؛ وقد يؤدي وجود مهلة سارية للعامل إلى تأخير الاستعادة النهائية مدة تصل إلى أربع دقائق إضافية.

curl 'https://fahrface.org/api/v1/face-age/jobs/JOB_ID' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY"

الأخطاء والحدود

تستخدم الاستجابات code/message/data. HTTP 400: طلب أو موافقة غير صالحين؛ 401: مفتاح غير صالح أو منتهي الصلاحية؛ 403: النطاق المطلوب غير متاح؛ 402: رصيد غير كافٍ؛ 404: المهمة غير موجودة أو لا تملكها؛ 409: مدخلات متغيرة؛ 413/415: حجم الصورة أو نوعها غير صالح؛ 429: تجاوز حد الطلبات أو التزامن أو الرصيد؛ 503: الخدمة غير متاحة. اتبع Retry-After، واستخدم مفتاح idempotency نفسه، وتحقق من message قبل إعادة المحاولة.

تنتهي صلاحية المفاتيح خلال عام واحد كحد أقصى. تشمل حدود الرصيد الأرصدة المحجوزة والناجحة؛ وتُعاد الأرصدة إلى الحد عند استردادها. يسمح الحساب بـ60 طلبًا في الدقيقة وبحد أقصى مهمتَي API نشطتين.

تُخزّن صور الوجوه مؤقتًا في مساحة تخزين خاصة، وتُحذف بعد اكتمال المعالجة النهائية، مع آلية احتياطية لحذفها خلال 24 ساعة. تعالج HF الصورة؛ والتقديرات ليست نصيحة طبية ولا إثباتًا للهوية أو العمر.