> واجهة برمجية (API) للبحث بالوجه: أرسل صورة واحدة بطلب POST، واحصل على الملفات العامة التي يظهر فيها هذا الوجه مع درجة ثقة لكل نتيجة. نقطة واحدة لكل عملية بحث، بدون اشتراك وبدون حد أدنى شهري. **API البحث بالوجه** # بحث بالوجه بالذكاء الاصطناعي، من كودك الخاص. واجهة برمجية **للبحث العكسي عن الوجوه** عبر الويب العام. أرسل صورة واحدة لوجه، واحصل على الصفحات والحسابات التي يظهر فيها هذا الوجه، كل واحدة مع درجة ثقة ورابط. نقطة واحدة لكل بحث، بالدولار، بدون اشتراك وبدون حد أدنى شهري. بدون مكالمة مبيعات · بدون حد أدنى شهري · النقاط لا تنتهي صلاحيتها متوفر أيضًا على [RapidAPI](https://rapidapi.com/muratcankuruoffical/api/trace-reverse-face-search-api) · [مواصفة OpenAPI](https://traceaifacescan.app/openapi.json) · [أمثلة كود على GitHub](https://github.com/muratcankuruoffical/reverse-face-search-api) · [مساحة Hugging Face](https://huggingface.co/spaces/muratcankuru/reverse-face-search) · [أداة Apify](https://apify.com/muratcankuru/reverse-face-search) - النتائج في نحو دقيقة - نقطة واحدة لكل بحث - REST + JSON، بلا تثبيت - محرك خاص بنا، لسنا وسيطًا **ماذا تفعل الـ API** ## صورة واحدة تدخل. كل تطابق عام يخرج. نفس المحرك الذي تعمل عليه لوحة التحكم، بنفس النتائج. الـ API ليست نسخة مخفَّضة. **البحث العكسي عن الوجوه** ### طابق الوجه، لا الملف. البحث العكسي العادي عن الصور يجد نسخًا من الصورة نفسها. هذه الخدمة تطابق الوجه، فصورة مختلفة لنفس الشخص — بملابس مختلفة، في سنة مختلفة — تظهر أيضًا كتطابق. **درجة الثقة** ### كل تطابق يحمل رقمًا. كل نتيجة تحمل درجة تشابه من 50 إلى 100 وفئة: محتمل من 70، قوي من 80، شبه مؤكد من 90. لا تُعرض أي نتيجة كحكم نهائي. **حسابات التواصل** ### الحساب، لا الصفحة فقط. عندما يعود الرابط إلى حساب، يُرجع اسم المستخدم والمنصة كحقول منفصلة — دون حاجة لتحليل الروابط من جانبك. **محرك خاص بنا** ### لسنا وسيطًا. تشغّل Trace خدمة بحث بالوجه خاصة بها. لهذا تكلّف عملية البحث سنتات لا دولارات، ولهذا لا نحتاج لتقييد عدد طلباتك. **بداية سريعة** ## ثلاث طلبات، من البداية إلى النهاية. المصادقة هي رأس واحد (header). لا حاجة لتثبيت SDK ولا لأي تبادل مصافحة. ### ابدأ فحصًا بصيغة multipart، باسم الحقل `image`. بصيغة JPEG أو PNG أو WebP، حتى 8 ميجابايت، وبحد أدنى 200 بكسل في الجانب الأقصر. رأس `Idempotency-Key` اختياري ويجعل إعادة المحاولة آمنة. ```bash curl -X POST https://traceaifacescan.app/api/v1/scans \ -H "Authorization: Bearer trk_live_..." \ -H "Idempotency-Key: $(uuidgen)" \ -F image=@face.jpg ``` **202 ACCEPTED** ```json { "id": "01m0jr1j5cbhwqsnt5qjx3zyd8", "status": "queued", "progress": 0, "locked": false, "match_count": 0, "credits_remaining": 9 } ``` ### استعلم حتى الانتهاء يستغرق البحث نحو 25–45 ثانية. استعلم كل ثانية أو ثانيتين حتى تصبح قيمة `status` هي `done` أو `failed`. ```bash curl https://traceaifacescan.app/api/v1/scans/01m0jr1j5cbhwqsnt5qjx3zyd8 \ -H "Authorization: Bearer trk_live_..." ``` **200 OK** ```json { "status": "done", "progress": 100, "locked": false, "match_count": 2, "matches": [ { "score": 88, "tier": "strong", "platform": "x", "handle": "@alexrivers88", "url": "https://x.com/alexrivers88", "preview_url": ".../scans/01m0.../previews/0" } ] } ``` ### اصرف النقطة الفحص الذي يُنشأ بلا نقاط متاحة يرجع بقيمة `locked: true` بلا تطابقات — لم يُبحث عن أي شيء. الكشف (reveal) طلب منفصل عن قصد: حتى لا يستطيع سكريبت يتصفح قائمة الفحوصات إفراغ رصيدك بالخطأ. ```bash curl -X POST \ https://traceaifacescan.app/api/v1/scans/01m0.../reveal \ -H "Authorization: Bearer trk_live_..." ``` **نقاط النهاية** ## كل الواجهة. سبع نقاط نهاية. التعريف القابل للقراءة الآلية موجود في [openapi.json](https://traceaifacescan.app/openapi.json)، والمرجع الكامل مع نماذج الاستجابة في [الوثائق](https://traceaifacescan.app/docs). - **POST** — `/v1/scans` — ابدأ فحصًا من صورة. - **GET** — `/v1/scans/{id}` — الحالة، التقدّم والتطابقات. - **GET** — `/v1/scans` — فحوصاتك، مقسّمة على صفحات. - **POST** — `/v1/scans/{id}/reveal` — اصرف نقطة وشغّل البحث الحقيقي. - **GET** — `/v1/scans/{id}/previews/{n}` — الصورة المصغّرة للوجه لتطابق واحد. - **DELETE** — `/v1/scans/{id}` — حذف الفحص وصورته ومعايناته. - **GET** — `/v1/account` — رصيد نقاطك. **الأخطاء والحدود** ## أعطال متوقعة. تُرجع الأخطاء بصيغة `application/problem+json` مع نص `code` ثابت. طابق حسب الكود دائمًا، لا حسب الرسالة النصية. - **402** — `insufficient_credits` — لا توجد نقاط متبقية. لم يُبحث عن أي شيء ولم يُخصم أي شيء. - **404** — `no_face_detected` — لا يوجد وجه في الصورة. يلزم صورة مختلفة، لا إعادة محاولة. - **429** — `rate_limited` — فقط بعد محاولات مصادقة فاشلة متكررة. رأس `Retry-After` يوضح الوقت. - **401** — `unauthorized` — مفتاح مفقود أو خاطئ أو مُلغى. - **503** — `provider_unavailable` — من جانبنا. النقطة المحجوزة لبحث فاشل تُعاد دائمًا. ### الحدود - **لا يوجد حد لمعدل الطلبات.** عمليات القراءة لا تُحسب ولا يوجد سقف لكل دقيقة. - الحد الحقيقي هو **رصيد نقاطك**: الفحص يكلّف نقطة، والقراءة لا تكلّف شيئًا. - الصور حتى **8 ميجابايت**، وبحد أدنى **200 بكسل** في الجانب الأقصر. - تُحذف الفحوصات وصورها بعد **30 يومًا**. طلب `DELETE` يحذفها فورًا. **الأسعار** ## نقطة واحدة، بحث واحد. نفس النقاط التي تستخدمها لوحة التحكم، من نفس الرصيد. بدون اشتراك، وبدون حد أدنى شهري، ولا تنتهي صلاحيتها. باقة 100 نقطة هي التي صُممت الـ API حولها. تُشترى بالبطاقة، أو بـ Telegram Stars، أو بالعملات المشفّرة — راجع [باقات النقاط](https://traceaifacescan.app/ar/#pricing). تحتاج كمية أكبر من أكبر باقة؟ [تواصل معنا](https://docs.google.com/forms/d/e/1FAIpQLSdVeyYm3BLWkEnmHToK5_JQynOHCctKTxMkBJp3PJf-pmaLYQ/viewform). **حدود صادقة** ## ما لا تفعله هذه الـ API. **ليست خدمة تحقق من الهوية.** التطابق هو درجة تشابه بين صورتين، لا تصريح عن هوية شخص. لا يوجد اسم، ولا عنوان، ولا رقم هاتف، ولا أي سجل من أي نوع في الاستجابة — فقط روابط عامة ورقم. **النتيجة الخالية ليست دليلًا على عدم الوجود.** تعني فقط أنه لم يُعثر على شيء في الجزء من الويب العام الذي نستطيع الوصول إليه. إذا لم يكن للشخص صورة عامة، فلا يوجد شيء لإيجاده، ولا يمكن لأي API تغيير ذلك. **لا شيء خلف تسجيل دخول يُلمس.** كل نتيجة هي صفحة كانت عامة بالفعل. **يجب ألا تُستخدم لفحوصات السجل الجنائي، أو التوظيف، أو الإقراض، أو التأمين، أو المراقبة، أو تطبيق القانون**، ولا ضد القاصرين. أرسل فقط الصور التي يحق لك البحث عنها. هذا مذكور في [شروط الاستخدام](https://traceaifacescan.app/ar/terms/) ونحن نطبّقه — المفتاح الذي يُستخدم بهذا الشكل يُلغى. **الأسئلة الشائعة** ## ما يسأله المطورون أولًا. ### ما هي واجهة البحث العكسي عن الوجوه؟ هي واجهة HTTP تأخذ صورة لوجه وتُرجع الأماكن الأخرى على الإنترنت العام التي يظهر فيها هذا الوجه نفسه. بخلاف البحث العكسي عن الصور الذي يقارن ملفات الصور، يقارن البحث بالوجه هندسة الوجه نفسها — فيتعرّف على نفس الشخص في صورة مختلفة تمامًا. نسخة Trace هي واجهة REST برسائل JSON: طلب POST واحد لبدء الفحص، وطلب GET واحد لقراءة التطابقات. ### كم تكلفة البحث بالوجه عبر الـ API؟ نقطة واحدة لكل بحث، والنقاط تُشترى في باقات بالدولار الأمريكي — من $4 لخمس نقاط إلى $50 لمئة نقطة. لا يوجد اشتراك، ولا حد أدنى شهري، ولا تاريخ انتهاء. تستخدم الـ API نفس رصيد لوحة التحكم. ### هل توجد باقة مجانية أو تجربة؟ لا يوجد بحث مجاني عبر الـ API. طلب من حساب بلا نقاط يُنشئ الفحص لكنه لا يبحث فيه: يرجع مقفلًا بلا تطابقات. لوحة التحكم تُظهر للزائر المسجَّل نتيجة نموذجية ثابتة ليرى شكل حالة مكتملة، أما الـ API فلا يُرجع ذلك عمدًا — فالنتيجة الوهمية شيء قد يَبني عليه سكريبت آلي. ### كم تستغرق عملية البحث؟ من 25 إلى 45 ثانية تقريبًا من البداية إلى النهاية، وقد تصل إلى 90 ثانية أحيانًا. لهذا السبب الـ API غير متزامنة: يُرجع طلب POST رمز 202 فورًا مع معرّف (id)، وتقوم أنت باستعلامه بشكل متكرر. إبقاء طلب HTTP مفتوحًا لمدة دقيقة كاملة قد يحوّل انقطاع الاتصال إلى بحث مُلغى. ### هل يمكنني استخدام روابط صور بدل رفع ملف؟ لا، ليس في الإصدار v1. قبول رابط يحوّل الـ API إلى وسيط SSRF — فنكون نجلب عناوين عشوائية من داخل شبكتنا بالنيابة عن المستخدم. إذا أُضيفت هذه الميزة لاحقًا فستكون بقائمة سماح (allowlist) مع رفض النطاقات الخاصة. ### هل يوجد حد لمعدل الطلبات على الـ API؟ لا. استدعِها بأقصى سرعة يستطيعها الكود — فعمليات القراءة لا تُحسب، ولا يوجد سقف لكل دقيقة. الشيء الوحيد الذي يحدّك هو رصيد نقاطك، لأن الفحص يكلّف نقطة والقراءة لا تكلّف شيئًا. يبقى هناك تقييد أمني واحد لا يراه المفتاح الصحيح أبدًا: محاولات المصادقة الفاشلة المتكررة من العنوان نفسه يتم تبطيئها، فيظل تخمين المفاتيح مكلفًا. ### هل استخدام واجهة برمجية للبحث بالوجه قانوني؟ يعتمد ذلك كليًا على استخدامك له ومكانك. التحقق من أن صورة على منصتك الخاصة تعود لنفس الشخص الذي يستخدمها أمر مختلف تمامًا عن بناء قاعدة بيانات للوجوه. بيانات الوجه فئة خاصة بموجب GDPR وKVKK، وأنت المتحكم في كل ما تُرسله إلينا. اقرأ شروط الاستخدام: فحوصات السجل الجنائي، التوظيف، الإقراض، التأمين، المراقبة وتطبيق القانون كلها خارج نطاق الاستخدام المسموح. ### هل هذه واجهة للتعرف على الوجوه أم للبحث العكسي عن الصور؟ هي واجهة للبحث بالوجه، وهو نوع محدد من التعرف على الوجوه. لا تقارن صورتين ترسلهما أنت، ولا تتحقق من وثيقة هوية، ولا تُرجع أي معلومة عن هوية الشخص. تأخذ صورة واحدة وتبحث في الويب العام عن صور أخرى لنفس الوجه، وتُرجع كل تطابق كرابط عام مع درجة تشابه. هذا أيضًا ما يميّزها عن واجهة البحث العكسي عن الصور: البحث العكسي عن الصور يطابق ملف الصورة نفسه، فيجد نسخًا من تلك الصورة بالتحديد، بينما هذه الواجهة تطابق هندسة الوجه وتجد نفس الوجه في صورة مختلفة. **API البحث بالوجه** ## ابدأ بطلب واحد. أنشئ مفتاحًا في لوحة التحكم وستعمل أول عملية curl فورًا.