واجهة كشف الصور بالذكاء الاصطناعي
توثيق كامل لدمج واجهة كشف الصور بالذكاء الاصطناعي من 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 وPillowocr: نتائج التعرف الضوئي لكشف العلامات المائيةml_model: نتائج نموذج التعلم الآليpreview_url: رابط معاينة الصورة إذا generate_preview = trueheatmap_status: حالة توليد الخريطة الحرارية ('pending' أو 'ready'). التوليد غير متزامن؛ في البداية قد يكون heatmap_url فارغاً.heatmap_url: رابط الخريطة الحرارية عند readiness؛ للصور بدرجة >= 20 فقطanalysis_results_status: حالة التحليل العميق ('pending'، 'done'، 'skipped'، أو null). عند pending استمر بالاستعلام؛ عند done راجع analysis_resultsanalysis_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 غير صالح أو منتهٍ
الحل:
- تحقق من صحة مفتاح API
- تأكد أن المفتاح نشط في حسابك
- جرّب إعادة إنشاء مفتاح API
"Not enough credits" (403)
السبب: أرصدة غير كافية لمعالجة الصور
الحل:
- تحقق من الأرصدة عبر /check-user-credits
- اشترِ أرصدة إضافية عند الحاجة
- قلّل حجم الصورة قبل الرفع لتوفير الأرصدة
مشاكل التحقق من المدخلات
"Unsupported file format" (400)
السبب: تنسيق صورة غير مدعوم أو غير صالح
الحل:
- تأكد أن التنسيق مدعوم (JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
- تأكد أن الملف غير تالف
- تحقق من رأس Content-Type عند الرفع
"File too large" (400)
السبب: حجم الملف يتجاوز 10 م.ب
الحل:
- صغّر الصورة أو اضغطها لتصبح أقل من 10 م.ب
- تحقق من الحجم قبل الرفع
- استخدم WebP عند الإمكان
مشاكل المعالجة
"Request timeout" (WebSocket)
السبب: استغرقت معالجة الصورة وقتاً طويلاً
الحل:
- جرّب صورة أصغر أو أقل تعقيداً
- تحقق من حمل الخدمة
- أعد الطلب
حالة المستند "failed"
السبب: فشلت المعالجة لأسباب متعددة
الحل:
- تأكد أن الصورة بين 1 ك.ب و10 م.ب
- تحقق من التنسيق المدعوم
- تأكد من اكتمال الرفع قبل الإرسال للكشف
- اتصل بالدعم إن استمرت المشكلة
مشاكل الرفع
"Image upload failed" (403/400)
السبب: رابط موقّع غير صالح أو منتهٍ، أو مشكلة تخزين
الحل:
- استخدم الرابط الموقّع فوراً بعد استلامه
- تحقق من رأس Content-Type
- أزل المسافات من اسم الملف
- ولّد رابطاً جديداً إن انتهى القديم
"Invalid pre-signed URL" (400)
السبب: اسم ملف فيه مسافات أو رابط منتهٍ/تالف
الحل:
- أزل المسافات من اسم الملف قبل طلب الرابط
- استخدم أحرفاً وأرقاماً وشرطات وشرطات سفلية فقط
- ولّد رابطاً موقّعاً جديداً عند الحاجة
الأسئلة الشائعة لواجهة API
إجابات على الأسئلة الأكثر شيوعاً حول واجهة كشف الصور بالذكاء الاصطناعي.