توثيق API
ISO 27001SOC 2 CertifiedGDPR Compliant

واجهة كشف الصور بالذكاء الاصطناعي

توثيق كامل لدمج واجهة كشف الصور بالذكاء الاصطناعي من TruthScan في تطبيقاتك.

جرّب بدون كود عبر نقطة نهاية FastAPI: https://detect-image.truthscan.com/docs

المصادقة

تستخدم TruthScan مفاتيح API للسماح بالوصول. يمكنك الحصول على مفتاحك في أعلى الصفحة في بوابة المطورين.

تتوقع TruthScan تضمين مفتاح API في جميع الطلبات في جسم يشبه ما يلي:

{
  "key": "YOUR API KEY GOES HERE"
}

استبدل YOUR API KEY GOES HERE بمفتاحك الشخصي.

كاشف الصور بالذكاء الاصطناعي

الكشف (3 خطوات)

سير عمل كشف الصور بالذكاء الاصطناعي:

  • الحصول على رابط رفع موقّع مسبقاً
  • رفع الصورة
  • إرسال الصورة للكشف

1. الحصول على رابط رفع موقّع مسبقاً

اطلب رابطاً موقّعاً مسبقاً من واجهة API لرفع ملف الصورة بأمان إلى خادم التخزين.

تنسيقات الملفات المدعومة

JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF

ملاحظة مهمة

أزل المسافات من اسم ملف الصورة عند طلب الرابط الموقّع.

GET https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg

مثال طلب

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg' \
--header 'apikey: YOUR API KEY GOES HERE'

مثال استجابة

{
  "status": "success",
  "presigned_url": "https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
  "file_path": "uploads/example.jpg"
}

2. رفع الصورة

استخدم 'presigned_url' لرفع الصورة عبر PUT. اضبط نوع المحتوى حسب تنسيق الصورة.

ملاحظة مهمة

أزل المسافات من اسم الملف عند الرفع.

مثال طلب

curl -X PUT 'https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...' \
  --header 'Content-Type: image/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg' # Attachment

حدود حجم الملف

  • الحد الأدنى: 1 ك.ب
  • الحد الأقصى: 10 م.ب

حافظ على اتساق التنسيق أثناء الرفع. الرفع الناجح يعيد 200.

3. إرسال الصورة للكشف

بعد الرفع، أرسل الصورة للكشف باستخدام 'file_path' من الخطوة السابقة.

POST https://detect-image.truthscan.com/detect

مثال طلب

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": false,
  "generate_analysis_details": true
}'

يشير 'FILE_PATH' إلى المسار من استجابة خطوة «الحصول على رابط رفع موقّع».

معاملات اختيارية

  • generate_preview: اضبط على 'true' لتوليد رابط معاينة (افتراضي: 'false')
  • document_type: نوع المستند (افتراضي: 'Image')
  • email: بريد إلكتروني للمعالجة
  • generate_analysis_details: اضبط على 'true' لتمكين تحليل ذكاء اصطناعي عميق (افتراضي: 'false'). عند التفعيل تتضمن استجابة الاستعلام analysis_results_status و analysis_results

مثال استجابة

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

تتضمن الاستجابة معرف صورة فريداً لمراقبة حالة الكشف.

استعلام

يقبل معرف الصورة من /detect ويعيد الحالة ونتيجة الكشف الكاملة بما فيها البيانات الوصفية وOCR وتحليل النموذج.

POST https://detect-image.truthscan.com/query

مثال طلب

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "IMAGE-ID-GOES-HERE"
}'

مثال استجابة

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "metadata": [
            "No Information Detected for Real/AI",
            "Could not find anything from ExifTool and Pillow metadata"
        ],
        "metadata_basic_source": "null",
        "ocr": [
            "OCR did not detect AI",
            0.0
        ],
        "ml_model": [
            "AI Generated",
            90.2371538185235
        ],
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

تفسير النتيجة

  • result: درجة من 1-100 لاحتمال أن تكون الصورة مُنشأة بالذكاء الاصطناعي؛ كلما ارتفعت زاد الاحتمال.
  • final_result: الحكم الإجمالي (مثل 'AI Generated' أو 'Real' أو 'Digitally Edited' أو 'AI Edited')
  • confidence: درجة ثقة الكشف
  • detection_step: مرحلة اكتمال الكشف: 1 = بيانات وصفية فقط، 2 = بيانات وصفية وOCR، 3 = الأشمل (بيانات وصفية وOCR ونتائج نموذج)
  • metadata: معلومات مستخرجة من بيانات الصورة الوصفية عبر ExifTool وPillow
  • ocr: نتائج التعرف الضوئي لكشف العلامات المائية
  • ml_model: نتائج نموذج التعلم الآلي
  • preview_url: رابط معاينة الصورة إذا generate_preview = true
  • heatmap_status: حالة توليد الخريطة الحرارية ('pending' أو 'ready'). التوليد غير متزامن؛ في البداية قد يكون heatmap_url فارغاً.
  • heatmap_url: رابط الخريطة الحرارية عند readiness؛ للصور بدرجة >= 20 فقط
  • analysis_results_status: حالة التحليل العميق ('pending'، 'done'، 'skipped'، أو null). عند pending استمر بالاستعلام؛ عند done راجع analysis_results
  • analysis_results: نتائج التحليل العميق عند done: agreement وconfidence وkeyIndicators وdetailedReasoning وvisualPatterns وrecommendations

ملاحظة مهمة

توليد الخريطة الحرارية غير متزامن. تُنشأ فقط للصور بدرجة >= 20.

مثلاً "result": 90.24 يدل على احتمال قوي لتوليد بالذكاء الاصطناعي، و"final_result": "AI Generated" حكم واضح، و"detection_step": 3 يعني اكتمال التحليل الكامل.

نتائج التحليل (تحليل عميق غير متزامن)

عند ضبط generate_analysis_details على true في /detect، يجري TruthScan تحليلاً عميقاً في الخلفية بعد الكشف الأول. قد يبقى analysis_results_status عند pending رغم جاهزية النتائج الأساسية.

1. النتيجة الأولية جاهزة (التحليل قد يكون قيد الانتظار)

مع generate_analysis_details: true واستعلام أول بحالة done، تكون result وfinal_result وconfidence جاهزة، لكن analysis_results_status قد يبقى pending.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

ماذا تفعل

يمكنك استخدام النتائج الأساسية فوراً. إذا احتجت التحليل العميق، استمر بالاستعلام بنفس معرف الصورة حتى يتغير analysis_results_status.

2. استمر بالاستعلام

تابع استدعاء /query بنفس معرف الصورة وراقب analysis_results_status حتى يصبح done.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}'

3. اكتمال التحليل — استجابة كاملة

عند done يحتوي analysis_results على التحليل العميق كاملاً.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": [
                "Uniform noise pattern typical of diffusion models"
            ],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

عند عدم توفر التحليل

إذا كان analysis_results_status skipped أو null أو غائباً، لن يُنتج تحليل عميق. قد يحدث إذا لم يُضبط generate_analysis_details أو لنوع صورة معين.

{
    "status": "done",
    "result": 12.5,
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

حقول نتائج التحليل

  • analysis_results_status: 'pending' = قيد المعالجة، 'done' = جاهز، 'skipped'/null = غير متاح
  • analysis_results.agreement: مدى اتفاق التحليل العميق مع الكشف الأول (strong / moderate / weak / disagreement)
  • analysis_results.confidence: ثقة التحليل العميق (0-100)
  • analysis_results.keyIndicators: مصفوفة شذوذ بصري مكتشف
  • analysis_results.detailedReasoning: شرح من جملتين إلى أربع عن التصنيف
  • analysis_results.visualPatterns: أنماط أسلوبية (مثل ضوضاء نماذج الانتشار)
  • analysis_results.recommendations: توصيات قابلة للتنفيذ للتحقق الإضافي

التحقق من أرصدة المستخدم

يقبل apikey في الرأس ويعيد تفاصيل الأرصدة.

GET https://detect-image.truthscan.com/check-user-credits

مثال طلب

curl -X 'GET' \
  'https://detect-image.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

مثال استجابة

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

فحص الصحة

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

GET https://detect-image.truthscan.com/health

مثال طلب

curl -X 'GET' \
  'https://detect-image.truthscan.com/health' \
  -H 'accept: application/json'

مثال استجابة

{
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z"
}

استجابة "healthy" تعني أن الخدمة تعمل بشكل طبيعي.

الأخطاء

تنجم معظم الأخطاء عن معاملات خاطئة. راجع كل طلب وجرّب نموذج الكود.

رموز الخطأ تتوافق مع REST:

رمز الخطأالمعنى
400طلب سيء — الطلب غير صالح.
403ممنوع — مفتاح API غير صالح أو أرصدة غير كافية لمعالجة الصور.
404غير موجود — المورد غير موجود.
405الطريقة غير مسموحة — طريقة وصول غير صالحة.
406غير مقبول — طُلب تنسيق ليس JSON.
410زال — أُزيل المورد من هذا المسار.
422جسم طلب غير صالح — تنسيق خاطئ أو معاملات ناقصة.
429طلبات كثيرة جداً — أبطئ وتيرة الطلبات.
500خطأ داخلي في الخادم — حاول لاحقاً.
503الخدمة غير متاحة — صيانة مؤقتة.

مشاكل شائعة وحلول

مشاكل المصادقة

"User verification failed" (403)

السبب: مفتاح API غير صالح أو منتهٍ

الحل:

  1. تحقق من صحة مفتاح API
  2. تأكد أن المفتاح نشط في حسابك
  3. جرّب إعادة إنشاء مفتاح API

"Not enough credits" (403)

السبب: أرصدة غير كافية لمعالجة الصور

الحل:

  1. تحقق من الأرصدة عبر /check-user-credits
  2. اشترِ أرصدة إضافية عند الحاجة
  3. قلّل حجم الصورة قبل الرفع لتوفير الأرصدة

مشاكل التحقق من المدخلات

"Unsupported file format" (400)

السبب: تنسيق صورة غير مدعوم أو غير صالح

الحل:

  1. تأكد أن التنسيق مدعوم (JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
  2. تأكد أن الملف غير تالف
  3. تحقق من رأس Content-Type عند الرفع

"File too large" (400)

السبب: حجم الملف يتجاوز 10 م.ب

الحل:

  1. صغّر الصورة أو اضغطها لتصبح أقل من 10 م.ب
  2. تحقق من الحجم قبل الرفع
  3. استخدم WebP عند الإمكان

مشاكل المعالجة

"Request timeout" (WebSocket)

السبب: استغرقت معالجة الصورة وقتاً طويلاً

الحل:

  1. جرّب صورة أصغر أو أقل تعقيداً
  2. تحقق من حمل الخدمة
  3. أعد الطلب

حالة المستند "failed"

السبب: فشلت المعالجة لأسباب متعددة

الحل:

  1. تأكد أن الصورة بين 1 ك.ب و10 م.ب
  2. تحقق من التنسيق المدعوم
  3. تأكد من اكتمال الرفع قبل الإرسال للكشف
  4. اتصل بالدعم إن استمرت المشكلة

مشاكل الرفع

"Image upload failed" (403/400)

السبب: رابط موقّع غير صالح أو منتهٍ، أو مشكلة تخزين

الحل:

  1. استخدم الرابط الموقّع فوراً بعد استلامه
  2. تحقق من رأس Content-Type
  3. أزل المسافات من اسم الملف
  4. ولّد رابطاً جديداً إن انتهى القديم

"Invalid pre-signed URL" (400)

السبب: اسم ملف فيه مسافات أو رابط منتهٍ/تالف

الحل:

  1. أزل المسافات من اسم الملف قبل طلب الرابط
  2. استخدم أحرفاً وأرقاماً وشرطات وشرطات سفلية فقط
  3. ولّد رابطاً موقّعاً جديداً عند الحاجة

تحتاج مساعدة؟

لمزيد من المعلومات أو الدعم الفني، اتصل بنا.

الأسئلة الشائعة لواجهة API

إجابات على الأسئلة الأكثر شيوعاً حول واجهة كشف الصور بالذكاء الاصطناعي.