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

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

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

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

المصادقة

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

تتوقع TruthScan تضمين مفتاح API في طلبات JSON إلى الخادم كما يلي (ما لم يوثّق المسار مصادقة بالترويسة فقط، مثل check-user-credits):

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

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

حدود معدل الطلبات

تطبّق الـ API لكل مفتاح API ميزانية طلبات في الدقيقة. مسارات الكتابة أعلى تكلفة من مسارات القراءة. الحد الافتراضي 60 طلبًا في الدقيقة — تواصل معنا إذا احتجت حدًا أعلى.

أوزان المسارات

كل طلب يخصم وزنه من ميزانيتك في الدقيقة:

المسارالنوعالوزن
POST /detectكتابة1
POST /bulk-uploadكتابة1
GET /get-presigned-urlقراءة0.2
GET /check-user-creditsقراءة0.2
POST /heatmap/{id}قراءة0.2
POST /preview/{id}قراءة0.2
POST /queryقراءةبلا حد
GET /healthقراءةبلا حد

مثال: بميزانية 60/دقيقة يمكنك إرسال حتى 60 طلب كتابة، أو نحو 300 طلب قراءة، أو أي مزيج يبقى مجموعه الموزون ≤ 60 في الدقيقة.

استجابة التقييد (HTTP 429)

عند تجاوز ميزانيتك في الدقيقة تعيد الـ API:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 3
X-RateLimit-Retry-After: 3
Content-Type: application/json

{
  "error": "Too many requests"
}

ترويسات استجابة حدود المعدل

  • X-RateLimit-Limit — سعتك في الدقيقة.
  • X-RateLimit-Remaining — الطلبات المتبقية في الدقيقة الحالية بعد هذا الطلب.
  • X-RateLimit-Reset — (في 429 فقط) الثواني حتى تتمكن من إرسال طلب كتابة آخر.
  • X-RateLimit-Retry-After — (في 429 فقط) القيمة نفسها بصيغة Retry-After.

السلوك الموصى به للعميل

  • راقب X-RateLimit-Remaining في الاستجابات الناجحة لضبط معدل طلباتك.
  • عند تلقي 429 انتظر على الأقل X-RateLimit-Retry-After ثانية قبل إعادة المحاولة — استخدم exponential backoff مع jitter.
  • للدفعات فضِّل POST /bulk-upload (طلب واحد يعالج حتى 50 صورة) بدلًا من العديد من /detect المتوازية.

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

Detect (عملية من ثلاث خطوات)

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

  • الحصول على رابط رفع موقّع مسبقًا (Pre-signed Upload URL)
  • رفع الصورة
  • إرسال الصورة إلى Detect

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

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

صيغ الملفات المدعومة

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

اسم الملف

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

بالنسبة لملفات PDF، تُكتشف الصورة الأولى فقط (سير ملف واحد).

استخدم اسم ملف بامتداد .zip على هذا المسار عندما تنوي إرسال أرشيف ZIP عبر bulk upload.

معاملات الاستعلام

  • file_name (مطلوب) — اسم الملف الأصلي؛ قد يُطبَّع الخادم (تُعدَّل المسافات والأحرف غير الآمنة). استخدم امتداد .zip للرفع المجمع.
  • expiration (اختياري) — مدة صلاحية الرابط الموقّع بالثواني (الافتراضي: 3600).
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://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...",
  "file_path": "uploads/example.jpg",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

document_id هو UUID جديد يُولَّد لطلب الرفع هذا (للربط والسجلات). يُعيَّن id الذي تستخدمه لـ /detect أو /bulk-upload عند إرسال تلك المسارات ما لم تمرّر id اختياريًا على /detect.

2. رفع الصورة

استخدم presigned_url المقدَّم لرفع الصورة عبر طلب PUT. تأكد من ضبط Content-Type بما يتوافق مع صيغة الصورة.

اسم الملف

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

اضبط Content-Type ليطابق امتداد الملف بدقة

  • image/jpeg: jpg, jpeg, jfif
  • image/png: png
  • image/webp: webp
  • image/heic: heic
  • image/heif: heif
  • image/avif: avif
  • image/bmp: bmp
  • image/tiff: tiff, tif
  • image/gif: gif
  • image/svg+xml: svg
  • application/pdf: pdf

أخطاء شائعة يجب تجنبها

  • لا تستخدم image/jpg (غير صحيح). استخدم image/jpeg.
  • لا تُطابق الملف مع ترويسة خاطئة (مثل ملف .png مع image/jpeg).
  • لا تغيّر الامتداد دون تحديث الترويسة (أو العكس).
  • لا تضمّن مسافات في أسماء الملفات عند الطلب أو الرفع.

مثال طلب

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...' \
  --header 'Content-Type: image/jpeg' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg'

أمثلة رفع إضافية (PNG, PDF, SVG)

curl -X PUT '<PRESIGNED_URL_FOR_example.png>' \
  --header 'Content-Type: image/png' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.png'
curl -X PUT '<PRESIGNED_URL_FOR_example.pdf>' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.pdf'
curl -X PUT '<PRESIGNED_URL_FOR_example.svg>' \
  --header 'Content-Type: image/svg+xml' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.svg'

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

  • الحد الأدنى لحجم الملف: 1KB
  • الحد الأقصى لحجم الملف: 10MB

تأكد من بقاء صيغة الملف متسقة أثناء الرفع. يعيد الرفع الناجح HTTP 200.

3. إرسال الصورة لكشف الذكاء الاصطناعي

بعد الرفع، أرسل الصورة للكشف بالإشارة إلى file_path من الخطة السابقة. لملفات PDF، تُحلَّل/تُكتشف الصورة الأولى فقط.

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": true
}'

FILE_PATH يشير إلى المسار المُعاد من خطوة الرابط الموقّع (مثل uploads/...). ابنِ الرابط الكامل مع مضيف التخزين كما في المثال.

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

  • id: سلسلة UUID اختيارية. إن حُذفت، يُولِّد الخادم document id جديدًا. إن وُجدت، يجب ألا تكون موجودة مسبقًا؛ وإلا تعيد API خطأ.
  • generate_preview: اضبطها على true لتوليد معاينة للصورة (الافتراضي: true). اضبطها على false لتخطي المعاينة.
  • document_type: نوع المستند (الافتراضي: Image).
  • email: عنوان بريد للمعالجة.
  • generate_analysis_details: اضبطها على false لتخطي التحليل التفصيلي (الافتراضي: true).
  • generate_heatmap_overlayed: يتحكم في كيفية إنتاج صورة heatmap عند توليدها (الافتراضي: true). عند true، تُمزج heatmap مع الصورة الأصلية (تراكب قياسي). عند false، تُعاد heatmap شفافة: صورة RGBA بخريطة تفعيل ملونة JET وقناة ألفا من النموذج، بخلفية شفافة لدمجها في واجهتك.
  • generate_heatmap_normalized: عند false، يتخطى توليد heatmap خطوة التطبيع لخريطة التفعيل (الافتراضي: true). استخدم مع generate_heatmap_overlayed للتحكم في مظهر heatmap.
  • model: تلميح نموذج أو توجيه (الافتراضي: generic). أمثلة مدعومة: generic، أو instance_id/model (مثل my-instance-id/generic) لإرسال المهمة إلى طابور مخصص. تُرفض قيم instance_id غير صالحة بـ 400.
  • user_agent: سلسلة اختيارية تُخزَّن مع المستند للتحليلات/الدعم.

مثال استجابة

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

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

Query: حالة الكشف والنتائج

للتحقق من الحالة وجلب النتائج، استخدم /query مع معرّف الصورة.

المصادقة: جسم الطلب يتضمن id فقط؛ لا يُرسل API key في هذا الاستدعاء. أي من يملك UUID يمكنه الاستعلام — اعتبر معرّفات المستندات حساسة إذا كنت تقيد من يرى النتائج.

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,
        "warnings": [
            { "type": "blur_dark", "label": "Blurred" },
            { "type": "watermark", "label": "Gemini", "confidence": 0.95 },
            { "type": "screen_recapture", "label": "screen", "metrics": { "is_screen": false }, "confidence": 99.99 }
        ]
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

مثال استجابة (/query، عناوين آمنة مفعّلة للمؤسسة)

{
    "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-detect.undetectable.ai/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
        "analysis_results_status": "ready",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detect.undetectable.ai/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}

مثال استجابة عند جاهزية نتائج التحليل

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "ready",
        "analysis_results": {
            "imageTags": ["person", "portrait", "outdoor", "vineyard", "smiling"],
            "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/..."
}

تفاصيل النتيجة

  • is_valid: يشير إلى صلاحية ملف الصورة (true/false).
  • detection_step: مرحلة اكتمال الكشف: 1 = بيانات وصفية فقط؛ 2 = بيانات وصفية و ocr؛ 3 = بيانات وصفية و ocr و ml_model.
  • final_result: الحكم الإجمالي (مثل "AI Generated"، "Real"، "Digitally Edited"، "AI Edited").
  • confidence: درجة ثقة الكشف.
  • metadata: معلومات مُستخرجة من بيانات الصورة الوصفية باستخدام ExifTool و Pillow.
  • metadata_basic_source: قد يبيّن ما إذا كانت الصورة مُلتقطة بكاميرا محددة، أو مُولَّدة بأداة ذكاء اصطناعي، أو مُعدَّلة ببرنامج تحرير.
  • ocr: نتيجة كشف العلامة المائية تحت الحقل التاريخي ocr. مصفوفة من عنصرين [label, score]: label فئة علامة مائية مكتشفة (مثل "Gemini") أو "OCR did not detect AI"؛ score على مقياس 0–100 (أو 0 عند عدم اليقين). يُلخَّص في warnings عند وجود label.
  • ml_model: نتائج نموذج التعلم الآلي.
  • warnings: مصفوفة اختيارية من كائنات تحذير متنوعة (نوع blur_dark، watermark، screen_recapture، إلخ). قد تكون فارغة أو مُحذفة.
  • preview_url: رابط معاينة إذا كان generate_preview مفعّلًا. قد يكون تخزينًا مباشرًا أو، عند تفعيل الروابط الآمنة، مسار API مثل https://<api-host>/preview/<document_id>.
  • heatmap_status: pending أو ready أو failed. توليد heatmap غير متزامن.
  • heatmap_url: heatmap عندما heatmap_status هو ready. المظهر يعتمد على generate_heatmap_overlayed. قد يكون تخزينًا مباشرًا أو مسار API https://<api-host>/heatmap/<document_id> (استخدم POST /heatmap/{id} مع المفتاح عند التفعيل الآمن).
  • analysis_results_status: pending أو ready أو skipped أو failed أو analyzing. يُحذف أو null عندما generate_analysis_details كان false.
  • analysis_results: تحليل نصي تفصيلي عند التفعيل؛ انظر شرح نتيجة التحليل أدناه.

شرح نتيجة التحليل

عند جاهزية analysis_results، يتضمن عادة: agreement (strong | moderate | weak | disagreement)، imageTags (حتى خمس وسوم قصيرة)، confidence (0–100)، keyIndicators، detailedReasoning، visualPatterns، و recommendations.

ملاحظات

  • توليد heatmap غير متزامن. استعلم /query عن heatmap_status و heatmap_url.
  • التحليل التفصيلي غير متزامن ما لم يكن generate_analysis_details=false. استعلم عن analysis_results_status و analysis_results.
  • الروابط الآمنة: عند التفعيل، قد تستخدم heatmap_url و preview_url مضيف API؛ جلب بالـ POST /heatmap/{id} و POST /preview/{id} مع مفتاحك (انظر أصول heatmap والمعاينة الآمنة).
  • استعلم /query مجددًا بعد جاهزية النتيجة الرئيسية لالتقاط heatmap و analysis_results عند اكتمالهما.

سلوك heatmap والتراكب

الملف عند heatmap_url يعكس generate_heatmap_overlayed و generate_heatmap_normalized من طلب /detect (أو /bulk-upload): التراكب الافتراضي (true) صورة عادية مع heatmap فوقها؛ false عادة PNG شفاف للدمج.

مثال: نتيجة ~90.24 مع final_result AI Generated و detection_step 3 تعني اكتمال المسار الكامل: بيانات وصفية و OCR و نموذج ML.

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

عندما generate_analysis_details هو true في /detect، قد يكتمل التحليل التفصيلي بعد النتيجة الرئيسية. استعلم /query حتى يصبح analysis_results_status جاهزًا (أو skipped/failed).

1. قد تكون النتيجة الأولية جاهزة قبل التحليل

الكشف الأساسي (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.

2. واصل الاستعلام

استدعِ /query بنفس id حتى يتغيّر analysis_results_status عن pending.

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. اكتمال التحليل

عندما analysis_results_status هو ready، يتضمن analysis_results: agreement، imageTags، confidence، keyIndicators، detailedReasoning، visualPatterns، و recommendations.

{
    "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": {
            "imageTags": [
                "person",
                "portrait",
                "outdoor",
                "vineyard",
                "smiling"
            ],
            "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 أو failed أو مفقودًا، أو generate_analysis_details كان false، اعتبر الكشف الأساسي نهائيًا.

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

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

  • analysis_results_status: pending | ready | skipped | failed | analyzing
  • analysis_results.agreement: strong | moderate | weak | disagreement
  • analysis_results.imageTags: وسوم وصفية قصيرة
  • analysis_results.confidence: 0–100
  • analysis_results.keyIndicators: مؤشرات محددة
  • analysis_results.detailedReasoning: شرح موجز
  • analysis_results.visualPatterns: أنماط أوسع
  • analysis_results.recommendations: خطوات تالية

Bulk Upload (ZIP)

أرسل عدة صور في طلب واحد برفع ZIP. السير يشبه الصورة الواحدة: presign (اسم ZIP) → PUT ZIP → POST /bulk-upload → استعلام /query.

1. الحصول على رابط رفع موقّع (ZIP)

استخدم get-presigned-url باسم ملف .zip (مثل images.zip).

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

مثال طلب

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

2. رفع ZIP

PUT للأرشيف إلى الرابط الموقّع مع Content-Type: application/zip.

curl -X PUT '<PRESIGNED_URL_FOR_images.zip>' \
  --header 'Content-Type: application/zip' \
  --header 'x-amz-acl: private' \
  --data-binary '@images.zip'

حدود ZIP

  • الحد الأقصى لحجم ZIP: 100MB
  • الحد الأقصى للصور في الدفعة: 50
  • حدود لكل صورة: حد أدنى 1KB، حد أقصى 10MB

الصيغ المدعومة داخل ZIP

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

ملفات PDF داخل ZIP غير مدعومة وتُتخطى.

تُحوَّل ملفات SVG إلى PNG قبل الكشف.

3. إرسال ZIP للكشف المجمع

POST /bulk-upload مع key و url يشيران إلى مسار ZIP المرفوع.

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

  • generate_preview: true لتوليد روابط معاينة (الافتراضي: false).
  • generate_analysis_details: true لتوليد تحليل تفصيلي (الافتراضي: false).
  • generate_heatmap_overlayed: نفس سلوك /detect (تراكب مقابل heatmap RGBA شفاف).
  • generate_heatmap_normalized: نفس سلوك /detect (الافتراضي: true).
  • model: مجال النموذج: generic، أو صيغة instance_id/model.

مثال طلب

curl -X 'POST' \
  'https://detect-image.truthscan.com/bulk-upload' \
  -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": false,
  "model": "generic"
}'

مثال استجابة

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

يُعيد id، status pending، و expected_count (عدد الصور من ZIP التي ستُحلَّل).

كيف تُحدَّث نتائج ZIP المجمع

  • بعد الإرسال، تكون الحالة pending حتى يبدأ المعالجة، ثم analyzing.
  • results تسرد كل صورة؛ الإدخالات المعلقة تكون result و result_details فارغة حتى الانتهاء.
  • قد تبقى heatmaps وتفاصيل التحليل معلقة داخل result_details حتى الجاهزية.
  • عند انتهاء كل صورة في results، تصبح الحالة الإجمالية done. قد تكون failed إذا تعذر إكمال الدفعة.
  • يمكنك استدعاء /query قبل انتهاء ZIP لرؤية نتائج جزئية.

4. استعلام نتائج Bulk Upload

استخدم POST /query مع id من /bulk-upload. نفس المسار كالصورة الواحدة؛ شكل الاستجابة يعتمد على كون id لصورة واحدة أو دفعة ZIP.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9"
}'

مثال استجابة (لا يزال قيد المعالجة)

{
  "id": "3b81fb24-dd23-40e7-ae95-82f823f44098",
  "status": "analyzing",
  "results": [
    {
      "id": "4600c7e5-00ec-469d-9117-ff20e0f1c1fa",
      "status": "done",
      "result": 44.0006,
      "result_details": {},
      "filename": "photo1.jpg",
      "preview_url": null
    },
    {
      "id": "2f770c89-352a-4d53-b6a3-a2147ca2c0ae",
      "status": "pending",
      "result": null,
      "result_details": null,
      "filename": "photo2.jpg",
      "preview_url": null
    }
  ],
  "skipped": []
}

حقول الاستجابة (ZIP مجمع)

  • id — معرّف طلب مجمع.
  • status — pending ثم analyzing ثم done أو failed.
  • results — إدخال لكل صورة (id، status، result، result_details، filename، preview_url عند التوفر).
  • skipped — ملفات لم تُحلَّل (نوع غير مدعوم، حجم، إلخ) مع status failed والسبب في result_details.

الفوترة: تُستهلك الأرصدة فقط للصور التي أُحلَّلت بنجاح. فشل تحويل SVG والملفات المتخطاة لا يُفوتر.

أصول heatmap والمعاينة الآمنة

عندما تشير heatmap_url أو preview_url في /query إلى مضيف API (وليس تخزينًا مباشرًا)، نزّل البايتات بـ POST ومفتاحك.

POST /heatmap/{id}

POST /preview/{id}

جسم الطلب JSON: { "key": "YOUR-API-KEY-GOES-HERE" }

استجابات heatmap (تحقق من HTTP status و Content-Type)

  • 200 + binary (image/png، إلخ) — ملف heatmap متاح. قد يُضبط X-Heatmap-Status.
  • 202 + JSON — heatmap_status pending؛ استعلم /query وأعد المحاولة.
  • 200 + JSON — لا heatmap للتقديم (ميزة اختيارية، فشل، إلخ)؛ ليس خطأ خادم.
  • 500 + JSON — heatmap_url مخزن لكن الملف تعذر تنزيله من التخزين؛ أعد لاحقًا.
  • 404 + JSON — معرّف المستند غير موجود.
  • 403 + JSON — مفتاح API لا يملك هذا المستند.

المعاينة: POST /preview/{id} يعيد بايتات المعاينة الخام. 404 مع JSON إذا لم تُولَّد معاينة (generate_preview كان false).

أمثلة

curl -X POST 'https://detect-image.truthscan.com/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output heatmap.png
curl -X POST 'https://detect-image.truthscan.com/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output preview.png

داخلي: مزامنة استخدام المؤسسة مع Stripe (سر المهمة)

للوظائف الخلفية الموثوقة فقط، وليس لعملاء API العامين. يتطلب ترويسة x-job-secret تطابق JOB_SECRET في الخادم. يزامن استخدام TruthScan المؤسسي المُقاس إلى Stripe لنطاق تاريخ.

POST /organizations/{org_id}/usage/sync-to-stripe

Headers: x-job-secret: <JOB_SECRET>

جسم JSON: start_date، end_date، و idempotency_id اختياري لـ Stripe meter idempotency.

يُعيد success، organization_id، total_documents، value_sent_to_stripe، report_date، message. 400 إذا لم تكن المؤسسة metered أو نقص stripe_customer_id عند الحاجة؛ 401 سر غير صالح؛ 404 مؤسسة غير موجودة؛ 500 أخطاء Stripe/إعداد.

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

يقبل هذا المسار مفتاح API للمستخدم عبر الترويسة ويعيد تفاصيل الأرصدة.

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
}

للتكاملات الخارجية، يُملأ حقل credits فقط.

فحص الصحة

تحقق من حالة خادم API.

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

مثال طلب

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

مثال استجابة

{
    "status": "healthy"
}

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

الأخطاء

تأتي معظم الأخطاء من معاملات غير صحيحة. راجع كل استدعاء وجرب الأمثلة.

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

رمز الخطأالمعنى
400Bad Request — الطلب غير صالح.
401Unauthorized — job secret غير صالح (مسارات الاستخدام الداخلي) أو فشل مصادقة مشابه.
403Forbidden — مفتاح API غير صالح، أو رفض وصول، أو أرصدة غير كافية للعملية.
404Not Found — المورد المطلوب غير موجود.
405Method Not Allowed — حاولت الوصول بأسلوب HTTP غير صالح لهذا المورد.
406Not Acceptable — طلبت صيغة ليست JSON.
410Gone — المورد في هذا المسار أُزيل.
422Invalid Request Body — جسم الطلب غير صحيح أو ناقص المعاملات.
429Too Many Requests — تجاوزت حد معدل مفتاح API (راجع حدود معدل الطلبات). الجسم {"error":"Too many requests"}؛ توضح ترويسة X-RateLimit-Retry-After عدد الثواني للانتظار قبل إعادة المحاولة.
500Internal Server Error — مشكلة في الخادم؛ أعد المحاولة لاحقًا.
503Service Unavailable — صيانة مؤقتة؛ أعد المحاولة لاحقًا.

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

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

"User verification failed" (403)

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

الحل:

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

"Not enough credits" (403)

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

الحل:

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

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

"Input URL cannot be empty" (400)

السبب: تم إرسال URL فارغ أو غير صالح

الحل:

  1. تأكد أن حقل url غير فارغ
  2. أزل المسافات الزائدة من أسماء الصور
  3. تحقق من ترميز URL

"Input email is empty" (400)

السبب: بريد مفقود لمعالجة URL

الحل:

  1. قدّم بريدًا صالحًا عند إرسال عناوين URL
  2. تحقق من صيغة البريد

"Unsupported image type" (400)

السبب: صيغة غير مدعومة

الحل:

  1. حوّل إلى صيغة مدعومة (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF)
  2. تحقق من صحة الامتداد

"File size is too small" (400)

السبب: الملف أصغر من الحد الأدنى

الحل:

  1. استخدم ملفًا أكبر (حد أدنى 1KB)
  2. تحقق من عدم تلف الملف أثناء الرفع

"File size exceeds limit" (400)

السبب: الملف كبير جدًا

الحل:

  1. اضغط أو صغّر الصورة؛ الحد الأقصى يحدده النشر (رسالة الخطأ تذكر الحد بالـ MB)
  2. جرّب صيغة أخرى

"Invalid file type" (400)

السبب: فشل التحقق من نوع الملف

الحل:

  1. تأكد أن الملف صورة صالحة
  2. تحقق من عدم تلف الملف
  3. تأكد أن MIME يطابق الامتداد

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

حالة الصورة "failed"

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

الحل:

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

"User not found"

السبب: معرّف مستخدم غير صالح

الحل:

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

"File metadata could not be fetched" (500)

السبب: تعذر الوصول إلى الملف المرفوع

الحل:

  1. تحقق أن الرفع نجح
  2. تأكد أن رابط الملف قابل للوصول
  3. أعد رفع الملف

مشاكل الرفع

"Image upload failed" (403/400)

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

الحل:

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

"Invalid pre-signed URL" (400)

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

الحل:

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

مشاكل الرفع المجمع

"URL must point to a ZIP file" (400)

السبب: الـ URL المُرسل إلى /bulk-upload لا يشير إلى ZIP

الحل:

  1. استخدم get-presigned-url?file_name=images.zip (أو اسم .zip آخر)
  2. ارفع ZIP صالحًا إلى الرابط الموقّع
  3. تأكد أن طلب bulk-upload يشير إلى مسار ZIP المرفوع

"ZIP file too large" (400)

السبب: ZIP يتجاوز الحد الأقصى (100MB)

الحل:

  1. قلّل عدد الصور أو اضغطها
  2. قسّم إلى عدة رفوع مجمعة

"Too many files" (400)

السبب: ZIP يحتوي أكثر من 50 صورة صالحة

الحل:

  1. قلّل إلى 50 صورة أو أقل لكل ZIP
  2. قسّم إلى عدة رفوع مجمعة

"No valid images found in ZIP" (400)

السبب: تُركت كل الملفات (صيغة غير مدعومة، حجم صغير، مسار غير صالح، إلخ)

الحل:

  1. استخدم صيغًا مدعومة (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
  2. PDF غير مدعوم في المجمع
  3. كل صورة 1KB على الأقل و10MB على الأكثر
  4. تجنب الملفات المخفية (تبدأ بـ .) وتجاوز المسار (..)

"Document is not a bulk upload (image-zip) result" (400)

السبب: id لا يطابق نوع الرفع (صورة واحدة مقابل دفعة ZIP)

الحل:

  1. استخدم id من /detect لإرسال صورة واحدة
  2. استخدم id من /bulk-upload لإرسال ZIP

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

لمزيد من المعلومات حول استخدام API أو للدعم الفني، تواصل معنا.

الأسئلة الشائعة حول API

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