> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # مطابقة الوجه API: مقارنة الوجه 1:1 > واجهة Didit لمطابقة الوجه 1:1 عبر POST /v3/face-match/ للتحقق من الهوية والتحكم في الوصول. استدلال أقل من 2 ثانية، دفع حسب الاستخدام، بدون حد أدنى شهري. ## OpenAPI ````yaml ar/openapi-25.json POST /v3/face-match/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/face-match/: post: tags: - Standalone APIs summary: مطابقة الوجه description: >- قارن بين صورتي وجه (1:1) واحصل على `score` للتشابه (0–100) بالإضافة إلى `status` بقيمة `Approved`/`Declined`. **آلية العمل.** يتم فك ترميز الصورتين وتحليلهما بواسطة نموذج بيومتري (اضبط `rotate_image=true` إذا كانت الصور الملتقطة قد تكون جانبية أو مقلوبة)، ثم يتم احتساب درجة التشابه بين الوجهين. تُرجع النتيجة التي تكون **أعلى تماماً** من `face_match_score_decline_threshold` (القيمة الافتراضية `30`) الحالة `status: "Approved"`؛ بينما تُرجع النتيجة المساوية له أو الأقل منه `Declined` مع تحذير `LOW_FACE_MATCH_SIMILARITY`. إذا تعذر احتساب الدرجة لأي زوج من الوجوه على الإطلاق، فسيستمر الاستدعاء في إرجاع `200` مع `status: "Declined"` وتحذير `NO_REFERENCE_IMAGE` — تكون قيمة `score` هي `null` في مسار الحفظ الافتراضي، أو `0` مع `save_api_request=false`. أرسل وجهاً واحداً واضحاً ومواجهاً للكاميرا لكل صورة للحصول على أفضل النتائج. **الفوترة.** تستهلك كل استجابة `200` رصيداً واحداً من API مطابقة الوجه (يُدفع من رصيد خطتك أو رصيد شحن الرصيد). عندما لا يتمكن رصيد المؤسسة من تغطية الاستدعاء، يُرجع endpoint الرمز `403` مع خطأ عدم كفاية الرصيد قبل معالجة أي صورة. **استمرار الجلسة (`save_api_request`، القيمة الافتراضية `true`).** عندما تكون القيمة `true`، يتم حفظ الاستدعاء كجلسة من نوع API: يظهر في Business Console، ويكون `request_id` المُرجع معرّف جلسة حقيقياً يمكنك تمريره إلى `GET /v3/session/{sessionId}/decision/`، ويتم تخزين كلتا الصورتين كصورتي المصدر/الهدف لمطابقة الوجه في الجلسة، ويتم إرسال حدث webhook من نوع `status.updated` إلى وجهات webhook التي قمت بتهيئتها. عندما تكون القيمة `false`، لا يتم تخزين أي شيء ويكون `request_id` عبارة عن UUID ارتباط يُستخدم لمرة واحدة ولا يمكن البحث عنه لاحقاً. **فهرس البحث بالوجه.** لا يُسجّل هذا الـ endpoint الوجوه أبداً في فهرس البحث بالوجه الخاص بك ولا يُجري أبداً فحص قائمة الحظر أو التكرار — استخدم `POST /v3/passive-liveness/` أو `POST /v3/face-search/` لهذه الأغراض. **البيئة التجريبية.** تتخطى مفاتيح API الخاصة بالبيئة التجريبية جميع عمليات المعالجة والفوترة: بعد التحقق من صحة الطلب (المدخلات المشوهة لا تزال تُرجع `400`)، يُرجع endpoint payload تجريبية ثابتة بحالة `Approved`، ولا يتم حفظ أي جلسة، ولا يُستهلك أي رصيد. **المصادقة.** أرسل مفتاح API الخاص بتطبيقك في الرأس `x-api-key`. تُرجع بيانات الاعتماد المفقودة أو غير الصالحة `403` (`{"detail": "You do not have permission to perform this action."}`) — لا تُرجع واجهة API هذه الرمز `401` أبداً. **حد المعدل.** ميزانية كتابة مشتركة تبلغ 300 طلب/دقيقة لكل مفتاح API عبر جميع endpoints الخاصة بـ POST/PATCH/DELETE؛ وتجاوزها يُرجع `429`. operationId: post_v3face-match parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image - ref_image properties: user_image: type: string format: binary description: >- صورة وجه لشخص حي أو صورة وجه مرشحة للتحقق منها (مثل صورة سيلفي). أرسل صورة أمامية واحدة مع ظهور وجه الشخص بوضوح وإضاءة جيدة. الامتدادات المسموح بها: `tiff`، `jpg`، `jpeg`، `png`، `webp`. أقصى حجم للرفع: **5 MB** (تُرفض الملفات الأكبر بـ `400`). يتم ضغط الصور تلقائيًا إلى ~0.5 MB قبل المعالجة، لذا فإن الدقة العالية جدًا لا تُحسّن الدقة. ref_image: type: string format: binary description: >- صورة وجه مرجعية للمقارنة معها (مثل صورة مستند الهوية أو صورة مسجلة مسبقاً). نفس قيود التنسيق والحجم الخاصة بـ `user_image`. face_match_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- حد التشابه (0–100) الذي يحدد `status` في الاستجابة. تؤدي الدرجة المحسوبة **المساوية لهذه القيمة أو الأقل منها** إلى تعيين `status` على `Declined` وإضافة تحذير `LOW_FACE_MATCH_SIMILARITY`؛ وتُرجع الدرجة الأعلى منها تماماً حالة `Approved`. القيمة الافتراضية `30` متساهلة — ارفعها (على سبيل المثال `50`–`60`) لإجراء تحقق أكثر صرامة. تُرجع القيم خارج النطاق 0–100 الرمز `400`. example: 50 rotate_image: type: boolean default: false description: >- عندما تكون `true`، تجرب الخدمة صور الإدخال بزيادات قدرها 90 درجة (0، 90، 180، 270) وتستخدم الاتجاه الذي يحقق أفضل كشف للوجه — مفيد للصور الملتقطة عبر الهاتف مع فقدان اتجاه EXIF. يضيف تأخيراً في الاستجابة، لذا لا تفعّله إلا إذا كنت لا تستطيع ضمان أن تكون الصور بالاتجاه الصحيح للأعلى. example: false save_api_request: type: boolean default: true description: >- عندما تكون القيمة `true` (الافتراضية)، يتم حفظ الاستدعاء كجلسة من نوع API — مرئية في Business Console، ويمكن استرجاعها عبر `GET /v3/session/{sessionId}/decision/` باستخدام `request_id` المُرجع، ويتم الإشعار بها عبر webhook لحدث `status.updated`. عندما تكون القيمة `false`، لا يتم تخزين أي شيء ويكون `request_id` عبارة عن معرّف UUID مؤقت للربط بالاستجابة فقط. example: true vendor_data: type: string description: >- سلسلة نصية مبهمة اختيارية (معرّف المستخدم الداخلي لديك، البريد الإلكتروني، UUID...) تُخزَّن في الجلسة المحفوظة وتُعاد في الاستجابة. استخدمها لربط استدعاءات API بسجلاتك الخاصة ولتصفية الجلسات لاحقاً. example: user-123 metadata: type: object additionalProperties: true description: >- كائن JSON اختياري يُخزن مع الجلسة (عندما يكون `save_api_request=true`) ويُعاد في الاستجابة. في طلبات multipart، أرسله كحقل سلسلة نصية بترميز JSON (مثل `metadata={"flow":"login"}`) — حيث يتم تحليله إلى كائن. example: flow: login device_id: abc123 example: user_image: (binary JPEG/PNG of the live selfie) ref_image: (binary JPEG/PNG of the reference photo) face_match_score_decline_threshold: 50 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: login responses: '200': description: >- تم احتساب مطابقة الوجه. الخاصية `face_match.score` عبارة عن رقم عشري بين 0 و100 (بمنزلتين عشريتين)؛ وتكون الحالة `status` هي `Approved` عندما تكون الدرجة أعلى تماماً من `face_match_score_decline_threshold`، وإلا فتكون `Declined` مع تحذير توضيحي. إذا كان الزوج ذا تشابه منخفض أو تعذر احتساب درجته فإنه يظل يُرجع `200` — تحقّق من `face_match.status` و`face_match.warnings`، وليس من رمز HTTP فقط. عندما تكون `save_api_request=true`، يكون `request_id` هو معرّف الجلسة المحفوظة. content: application/json: examples: Approved: summary: الشخص نفسه — النتيجة أعلى من الحد value: request_id: f9f5a777-8002-44c6-baaf-128bcfd6e226 face_match: status: Approved score: 99.41 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 653 - 745 - 1691 - 2185 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: [] vendor_data: user-123 metadata: flow: login created_at: '2026-06-12T01:04:42.763237+00:00' Declined - low similarity: summary: الدرجة عند حد الرفض أو أدنى منه value: request_id: 7cdda24e-311a-46d3-a3bb-e5d9b564ce73 face_match: status: Declined score: 24.87 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 156 - 234 - 679 - 898 confidence: 0.717775 age: 41.2 gender: male race: null best_angle: 0 warnings: - risk: LOW_FACE_MATCH_SIMILARITY feature: FACEMATCH additional_data: null log_type: error short_description: Low face match similarity long_description: >- The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:08:19.859116+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- معرّف الجلسة المحفوظة عندما تكون `save_api_request=true` (يمكن استخدامه مع `GET /v3/session/{sessionId}/decision/`)؛ وإلا فسيكون UUID ارتباط مؤقت. face_match: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` عندما تكون درجة التشابه أعلى من `face_match_score_decline_threshold` بشكل صارم وأمكن احتساب الدرجة؛ و`Declined` خلاف ذلك (يوضح تحذير السبب). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- درجة التشابه من 0 إلى 100 — ثقة النموذج في أن الصورتين تعودان للشخص نفسه. يتم تقريبها إلى منزلتين عشريتين فقط عندما تكون قيمة `save_api_request` هي true؛ ومع `save_api_request=false` يتم إرجاع القيمة العشرية الخام. تكون `null` عندما يتعذر احتساب الدرجة لأي زوج من الوجوه (مع القيمة الافتراضية `save_api_request=true`)؛ ومع `save_api_request=false` قد تظهر الحالة نفسها على أنها `score: 0`. في كلتا الحالتين، يظهر تحذير `NO_REFERENCE_IMAGE` وتكون `status` هي `Declined`. example: 99.41 user_image: type: object description: نتائج كشف الوجه للصور التي تم تحليلها. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- المربع المحيط للوجه المكتشف كإحداثيات بكسل `[x_min, y_min, x_max, y_max]` في الصورة المُعالجة. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: درجة الثقة في كشف الوجه (0–1). example: 0.732973 age: type: number format: float description: >- العمر المقدّر بالنموذج للوجه المكتشف، بالسنوات. لأغراض إعلامية فقط — لا يؤثر على قرار مطابقة الوجه. example: 26.91 gender: type: string description: >- الجنس المتوقع بالنموذج للوجه المكتشف (`male` أو `female`). لأغراض إعلامية فقط. example: male race: type: string nullable: true description: >- حقل محجوز — دائماً `null` في الاستجابات من هذا endpoint. example: null description: إدخال واحد لكل وجه مكتشف. best_angle: type: integer description: >- زاوية التدوير (بالدرجات: 0 أو 90 أو 180 أو 270) التي حققت أفضل كشف للوجه. تكون غير صفرية فقط عندما يصحح `rotate_image=true` الاتجاه. example: 0 ref_image: type: object description: >- نتائج كشف الوجه للصورة المرجعية، بنفس بنية `user_image`. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- المربع المحيط للوجه المكتشف كإحداثيات بكسل `[x_min, y_min, x_max, y_max]` في الصورة المُعالجة. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: درجة الثقة في كشف الوجه (0–1). example: 0.732973 age: type: number format: float description: >- العمر المقدّر بالنموذج للوجه المكتشف، بالسنوات. لأغراض إعلامية فقط — لا يؤثر على قرار مطابقة الوجه. example: 26.91 gender: type: string description: >- الجنس المتوقع بالنموذج للوجه المكتشف (`male` أو `female`). لأغراض إعلامية فقط. example: male race: type: string nullable: true description: >- حقل محجوز — دائماً `null` في الاستجابات من هذا endpoint. example: null description: إدخال واحد لكل وجه مكتشف. best_angle: type: integer example: 0 warnings: type: array description: >- فارغ عند الموافقة السليمة. `NO_REFERENCE_IMAGE` (`error`) — تعذر احتساب درجات أي زوج من الوجوه؛ `LOW_FACE_MATCH_SIMILARITY` (`error`) — النتيجة عند حد الرفض أو دونه. يؤدي أيٌّ من هذه الإدخالات إلى تعيين `status` إلى `Declined`. items: type: object properties: risk: type: string enum: - NO_REFERENCE_IMAGE - LOW_FACE_MATCH_SIMILARITY description: رمز مخاطر مقروء آلياً. feature: type: string enum: - FACEMATCH description: >- الميزة التي أصدرت التحذير. دائماً `FACEMATCH` في هذا الـ endpoint. additional_data: type: object nullable: true additionalProperties: true description: دائماً `null` للتحذيرات الخاصة بمطابقة الوجه. log_type: type: string enum: - error - warning - information description: >- مستوى الخطورة. تحذيرات `error` تنقل `status` إلى `Declined`؛ وإدخالات `warning` و`information` استشارية ولا تؤدي إلى الرفض بمفردها أبداً. short_description: type: string description: ملخص للمخاطر في سطر واحد مقروء للبشر. long_description: type: string description: تفسير سهل القراءة للمخاطر. vendor_data: type: string nullable: true description: نسخة مطابقة من `vendor_data` التي أرسلتها، أو `null`. metadata: type: object nullable: true additionalProperties: true description: نسخة مطابقة من كائن `metadata` الذي أرسلته، أو `null`. created_at: type: string format: date-time description: >- طابع زمني بتنسيق ISO 8601 (بالتوقيت العالمي المنسق UTC) لوقت إنشاء الاستجابة، مثل `2026-06-12T01:04:42.763237+00:00`. '400': description: >- خطأ في التحقق. يتم إرجاعه عندما تكون الصورة المطلوبة مفقودة، أو يتجاوز حجمها 5 MB، أو يكون امتدادها غير مدعوم، أو عندما يكون أحد الخيارات خارج النطاق. يكون نص الاستجابة هو غلاف أخطاء الحقول القياسي لـ DRF: مصفوفة واحدة من الرسائل لكل حقل مخالف. content: application/json: examples: Missing required image: summary: '`ref_image` (أو `user_image`) غير مدرج في بيانات النموذج' value: ref_image: - No file was submitted. Unsupported file extension: summary: امتداد الملف خارج tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: يتجاوز الملف المرفوع حد 5 ميجابايت value: user_image: - File size should not exceed 5 MB Threshold out of range: summary: '`face_match_score_decline_threshold` خارج النطاق 0–100' value: face_match_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: >- تم رفض الإذن. يُرجع عند فقدان الرأس `x-api-key`، وأيضاً عندما لا يتمكن رصيد المؤسسة الطالبة من تغطية الاستدعاء؛ ويُرجع المفتاح الخاطئ أو الملغى أو منتهي الصلاحية `401`. يؤدي المفتاح المفقود إلى إرجاع `403` مع `{"detail": ...}`؛ ويؤدي المفتاح الخاطئ أو الملغى أو منتهي الصلاحية إلى إرجاع `401`. يُرجع نقص الرصيد `403` مع `{"error": ...}` قبل إجراء أي معالجة للصور. content: application/json: examples: Missing or invalid API key: summary: لا يوجد رأس `x-api-key`، أو أن المفتاح غير صالح/ملغى value: detail: You do not have permission to perform this action. Not enough credits: summary: رصيد المؤسسة لا يمكنه تغطية تكلفة الاستدعاء value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- تم تجاوز حد المعدل. تشترك نقاط endpoint الخاصة بـ POST/PATCH/DELETE في ميزانية قدرها 300 طلب كتابة في الدقيقة لكل مفتاح API (إنشاء المعاملات واستيعاب الأحداث لهما ميزانية منفصلة تبلغ 600). تتضمن الاستجابة رؤوس `X-RateLimit-Limit` و`X-RateLimit-Remaining` و`X-RateLimit-Reset` و`Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: أكثر من 300 طلب كتابة في الدقيقة الحالية value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/face-match/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'ref_image=@./id_portrait.jpg' \ -F 'face_match_score_decline_threshold=50' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.face_match.compare( user_image=open("user_image.jpg", "rb"), ref_image=open("ref_image.jpg", "rb"), face_match_score_decline_threshold=50.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "login"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.faceMatch.compare({ user_image: await fileFromPath("user_image.jpg"), ref_image: await fileFromPath("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"login\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.FaceMatchCompareParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceMatch().compare(FaceMatchCompareParams.builder() .userImage(Path.of("user_image.jpg")) .refImage(Path.of("ref_image.jpg")) .faceMatchScoreDeclineThreshold(50.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "login")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceMatch->compare([ 'user_image' => File::fromPath('user_image.jpg'), 'ref_image' => File::fromPath('ref_image.jpg'), 'face_match_score_decline_threshold' => 50.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'login'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_match.compare( user_image: Pathname("user_image.jpg"), ref_image: Pathname("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.FaceMatch.CompareAsync(new FaceMatchCompareParams { UserImage = FileUpload.FromPath("user_image.jpg"), RefImage = FileUpload.FromPath("ref_image.jpg"), FaceMatchScoreDeclineThreshold = 50.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "login" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.