توثيق واجهة البرمجة

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

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

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

المصادقة

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

يُتوقع تضمين مفتاح واجهة البرمجة في جميع الطلبات في جسم الطلب كما يلي:

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

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

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

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

سير عمل كشف الفيديو:

إرسال الفيديو للكشف (رفع multipart)
استعلام المهمة لاسترجاع النتائج

1. إرسال الفيديو للكشف

ارفعوا ملف الفيديو مباشرة. يتحقق الخادم من الملف.

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

MP4, MOV, AVI, MKV, WEBM

حدود الحجم

الحد الأدنى: 1 كيلوبايت
الحد الأقصى: 100 ميجابايت

POST https://detect-video.truthscan.com/detect-file

مثال طلب

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4'

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

document_type: نوع المستند (افتراضي: Video)
email: بريد اختياري للمعالجة

مثال استجابة

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

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

2. استعلام حالة الكشف والنتائج

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

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

مثال طلب

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

مثال استجابة

{
    "id": "bfd136fc-666b-42d0-89cf-0e9690c98f21",
    "status": "done",
    "result": 0.101969311406719,
    "result_details": {
        "final_stage": "watermark",
        "metadata": {
            "status": "ok",
            "prediction": "no_detection",
            "confidence": 0.0
        },
        "watermark": {
            "prediction": "ai_generated (watermark)",
            "confidence": 1.0
        },
        "ml": {
            "aggregate": {
                "prob_fake": 0.1019693114067195,
                "label": "cancelled",
                "n_frames": 256,
                "latency_sec": 23.319
            }
        },
        "latency_sec": 24.017
    },
    "preview_url": null
}

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

status: "pending" أو "analyzing" أو "done" أو "failed"
result: درجة قياسية في [0.0، 1.0] من prob_fake
final_stage: آخر مرحلة ساهمت: metadata أو watermark أو ml
metadata: تضبط غالباً prediction: no_detection وconfidence: 0.0. الحالة قد تكون reject أو reencode أو ok
watermark: طريقة تعتمد على عيّنات إطارات وتباين بكسل
ml: مصنف على إطارات عيّنة. يعيد prob_fake وlabel (ai_generated إذا prob_fake ≥ 0.5)
latency_sec: زمن المسار الكامل

حقل "status": pending (في الطابور)، analyzing (جارٍ الكشف)، done (النتائج جاهزة)، failed (فشل المعالجة).

التحقق من اعتمادات المستخدم

يقبل نقطة النهاية مفتاح واجهة البرمجة عبر الترويسة ويعيد تفاصيل الاعتمادات.

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

مثال طلب

curl -X 'GET' \
  'https://detect-video.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-video.truthscan.com/health

مثال طلب

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

مثال استجابة

{
    "status": "healthy"
}

الأخطاء

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

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

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

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

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

"User verification failed" (403)

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

الحل:

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

"Not enough credits" (403)

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

الحل:

تحققوا من الاعتمادات عبر /check-user-credits
اشترُوا اعتمادات إضافية عند الحاجة

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

"Unsupported video type" (400)

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

الحل:

حوّلوا الفيديو إلى صيغة مدعومة (MP4، MOV، AVI، MKV، WEBM)
تأكدوا من الامتداد ونوع MIME

"File size exceeds limit" (400)

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

الحل:

اضغطوا أو قصّوا أو أعدوا الترميز (حد أقصى 100 ميجابايت)
استخدموا ترميزاً أكثر كفاءة

"File size is too small" (400)

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

الحل:

استخدموا ملفاً أكبر (حد أدنى 1 كيلوبايت)
تأكدوا من عدم تلف الملف أثناء الرفع

"Invalid file type" (400)

السبب: فشل التحقق من النوع (MIME خاطئ أو ملف تالف)

الحل:

تأكدوا أن الملف فيديو صالح
طابقوا MIME مع الامتداد
أعيدوا التصدير أو الترميز عند الحاجة

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

حالة الفيديو "failed"

السبب: فشل المعالجة (حاوية غير مقروءة، أخطاء فك ترميز)

الحل:

استخدموا حاوية/ترميزاً شائعاً (يُفضّل H.264/AAC في MP4)
أعيدوا الترميز بإعداد قياسي (مثل ffmpeg) وأعيدوا الرفع
تأكدوا من الامتثال لحدود الحجم والصيغة

حالة "timeout" أو معالجة طويلة

السبب: المعالجة أطول من المتوقع أو انتهت المهلة

الحل:

انتظروا ثم أعيدوا الاستعلام عبر /query
تأكدوا من صيغة وحجم الملف
تواصلوا مع الدعم إذا استمرت المشكلة

"User not found"

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

الحل:

تحققوا من ربط المفتاح بحساب نشط
تأكدوا من صحة مستخدم التكامل
أعيدوا المصادقة عند الحاجة

"File metadata could not be fetched" (500)

السبب: تعذّر الوصول للملف أو تحليله

الحل:

تأكدوا من اكتمال الرفع
تحققوا من سلامة الملف
أعيدوا الرفع

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

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

اتصل بنا

الأسئلة الشائعة لواجهة البرمجة

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