توثيق API

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

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

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

المصادقة

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

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

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

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

في سيناريوهات WebSocket، أرسل معرّف المؤسسة ضمن الرابط. يمكنك الحصول عليه في أعلى الصفحة في بوابة المطورين.

تتوقع TruthScan تضمين معرّف المؤسسة في رابط جميع طلبات WebSocket. يبدو التوثيق كالتالي:

wss://detect-text.truthscan.com/ws/$ORG_ID

استبدل $ORG_ID بمعرّف مؤسستك الشخصي.

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

كشف

يُرسل هذا المسار نصاً للكشف. يُنصح بـ200 كلمة على الأقل لأفضل دقة.

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

العتبة

يُعيد المسار درجة "result" من 1-100. دون 50 يُعتبر بُشَراً بشكل قاطع. 50-60 احتمال ذكاء اصطناعي. فوق 60 ذكاء اصطناعي مؤكد. هذا أدق نتيجة بدقة تزيد عن 99%.

درجات كاشفات أخرى مثل Writer وCopyleaks تقريبية وأقل دقة من درجة "result" الرئيسية.

أسطر جديدة

عند إرسال JSON، صِغ الأسطر كـ \n داخل النص.

مثال طلب

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "On Citizen science\nCitizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "retry_count": 0,
  "generate_analysis_details": true
}'

يجب أن يكون المدخل أقل من 30,000 كلمة.

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

model: نموذج كشف الذكاء الاصطناعي المستخدم (الافتراضي: 'xlm_ud_detector')
retry_count: عدد إعادات المحاولة عند فشل المعالجة (الافتراضي: 0)
generate_analysis_details: اضبطه على 'true' لتفعيل نتائج التحليل العميق بالذكاء الاصطناعي (الافتراضي: 'false'). عند التفعيل، تتضمن استجابة /query حقول analysis_results_status و analysis_results.

مثال استجابة

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
    "model": "xlm_ud_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

تتضمن الاستجابة معرف المستند المُسند. يُصفّ المستند للمعالجة. استخدم /query لحالة الطلب. متوسط زمن الكشف 2-4 ثوانٍ وقد يزيد حسب عدد الكلمات.

استعلام

يقبل معرف المستند من /detect ويعيد الحالة ونتيجة الكشف من كاشفات طرف ثالث.

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

مثال طلب

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

مثال استجابة

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "result": 12.0,
    "label": "Human",
    "result_details": {
        "scoreGptZero": 50.0,
        "scoreOpenAI": 0.0,
        "scoreWriter": 0.0,
        "scoreCrossPlag": 0.0,
        "scoreCopyLeaks": 50.0,
        "scoreSapling": 0.0,
        "scoreContentAtScale": 0.0,
        "scoreZeroGPT": 50.0,
        "human": 88.0,
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "result_categories": {
        "advanced": 12,
        "standard": 12
    },
    "status": "done",
    "retry_count": 0
}

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

result: درجة من 0-100 تشير إلى احتمال أن يكون النص من توليد ذكاء اصطناعي. دون 50 = بشري بشكل قاطع. 50-60 = احتمال ذكاء اصطناعي. فوق 60 = ذكاء اصطناعي مؤكد.
label: التصنيف الإجمالي: 'Human' أو 'AI' أو 'Paraphrase'
result_details scores: درجات تقريبية من كاشفات طرف ثالث: GPTZero وOpenAI وWriter وCrossPlag وCopyLeaks وSapling وContentAtScale وZeroGPT (كل منها 0 أو 50 أو 100)
human: متوسط درجات جميع كاشفات الطرف الثالث ويعكس مدى ظهور النص إنسانياً
result_categories.advanced: فئة نتيجة متقدمة بتدرج درجات (1-99 منسّق)
result_categories.standard: فئة نتيجة قياسية
analysis_results_status: حالة التحليل العميق بالذكاء الاصطناعي ('pending' أو 'ready' أو 'skipped' أو null). عند 'pending' استمر باستعلام /query — التحليل لا يزال يعمل في الخلفية. عند 'ready' يحتوي analysis_results على التحليل المكتمل. عند 'skipped' أو null أو غياب الحقل، التحليل العميق غير متاح لهذا النص.
analysis_results: نتائج التحليل العميق (متاحة عندما analysis_results_status = 'ready'). تتضمن: agreement (strong/moderate/weak/disagreement) وconfidence (0-100) وkeyIndicators (مؤشرات نصية) وdetailedReasoning (شرح) وlinguisticPatterns (أنماط لغوية) وrecommendations (توصيات عملية).

مثلاً "result": 12.0 يعبر عن «إنسانية» المدخل؛ دون 50% يعني نصاً بشرياً بشكل قاطع. تفاصيل result_details توضح إنسانية المدخل لكل كاشف، مثل "scoreZeroGPT": 50.0.

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

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

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

مثال طلب

curl -X 'GET' \
  'https://detect-text.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
}

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

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

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

عند الإرسال مع generate_analysis_details: true وأول استعلام بحالة 'done'، تكون نتائج الكشف الأساسية (result وlabel وresult_details) جاهزة. لكن قد يكون analysis_results_status = 'pending' — أي أن التحليل العميق لا يزال يعمل في الخلفية.

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

ما الذي عليك فعله

يمكنك استخدام نتائج الكشف الأولية (result وlabel ودرجات result_details) فوراً. إذا احتجت التحليل العميق أيضاً، استمر باستدعاء /query بنفس معرف المستند حتى يتغير analysis_results_status عن 'pending'.

2. الاستمرار بالاستعلام لنتائج التحليل

استمر باستدعاء /query بنفس معرف المستند. راقب analysis_results_status في كل استجابة. عند الانتقال من 'pending' إلى 'ready' يُملأ كائن analysis_results.

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

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

عندما يصبح analysis_results_status = 'ready'، يحتوي analysis_results على التحليل العميق الكامل: مستوى الاتفاق والثقة والمؤشرات الرئيسية والتبرير اللغوي والأنماط والتوصيات.

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "ready",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 78,
            "keyIndicators": [
                "Highly consistent sentence structure throughout",
                "Formulaic transitions between paragraphs",
                "Lack of personal voice or idiosyncratic expressions"
            ],
            "detailedReasoning": "The text exhibits hallmarks of AI-generated content including uniform sentence complexity, predictable paragraph transitions, and an absence of personal stylistic quirks. The vocabulary choices are sophisticated but lack the natural variation typical of human writing.",
            "linguisticPatterns": [
                "Uniform sentence length distribution",
                "Repetitive use of hedging language",
                "Absence of colloquialisms or informal markers"
            ],
            "recommendations": [
                "Cross-reference with the original source if available",
                "Check for consistent writing style across longer documents",
                "Compare with known writing samples from the claimed author",
                "Consider the context in which the text was produced"
            ]
        }
    },
    "result_categories": {
        "advanced": 73,
        "standard": 73
    }
}

عندما لا يكون التحليل متاحاً

إذا كان analysis_results_status = 'skipped' أو null أو غير موجود، لن يُنتج تحليل عميق لهذا النص. يحدث ذلك عندما لا يُضبط 'generate_analysis_details' على 'true' في /detect أو في سيناريوهات معالجة معيّنة. اعتبر نتائج الكشف الأولية نهائية.

{
    "status": "done",
    "result": 12.0,
    "label": "Human",
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

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

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

كشف الذكاء الاصطناعي على مستوى الجمل

يعمل كاشف الجمل على بروتوكول WebSocket.

الخطوات للحصول على نتائج على مستوى الجملة:

الاتصال بـ WebSocket
الاستماع لجميع الأحداث
إرسال طلب document_watch
استلام حدث document_id
استخدام المعرّف وإرسال المستند للكشف
استلام أحداث document_chunk مع نتيجة كل جملة
عند انتهاء المعالجة يصل حدث document_done

الاتصال بـ WebSocket

يُمكّن هذا المسار من إنشاء اتصال WebSocket

wss://detect-text.truthscan.com/ws/$ORG_ID

مثال كود

ws = new WebSocket("wss://detect-text.truthscan.com/ws/1722238709737x2194626580942121212");

الاستماع لأحداث WebSocket

بعد الاتصال، استمع للأحداث الواردة عبر الاتصال.

مثال كود

ws.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

إرسال طلب document_watch

أعِل عن رغبتك في إرسال مستند عبر document_watch على WebSocket

مثال كود

ws.send(JSON.stringify({
    "event_type": "document_watch",
    "api_key": "$API_KEY",
}))

استلام حدث document_id

بعد document_watch يعيد الخادم حدث document_id.

مثال استجابة

{
  "event_type": "document_id",
  "success": true,
  "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

إرسال طلب كشف

استخدم المعرّف من document_id وأرسل المستند للكشف

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

مثال طلب

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'

استلام نتائج على مستوى الجمل

ابدأ باستلام أحداث document_chunk؛ تُعيد كل جملة مع نتيجة الكشف على مستوى الجملة

أمثلة استجابات

{
    "event_type": "document_chunk",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector",
    "chunk": "Citizen science involves the public in scientific research.",
    "result": 0.714
}

عند انتهاء المعالجة يصل حدث document_done.

أمثلة استجابات

{
    "event_type": "document_done",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector"
}

التعامل مع الأعطال

عند خطأ أثناء الكشف، يُرسل document_error لعميل WebSocket. يجب على الواجهة عرض رسالة مناسبة.

مثلاً يُرسل REQUEST_TIMEOUT إذا تجاوزت الأحداث 20 ثانية بين المقاطع.

{
    "event_type": "document_error",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "error_code": "REQUEST_TIMEOUT",
    "message": "Request timeout. Took 20 seconds."
}

الإلغاء

قد يرغب المستخدم في إلغاء العملية بإغلاق النافذة أو الإلغاء.

في هذه الحالة أرسل حدث document_halt

أمثلة استجابات

{
    "event_type": "document_halt",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

الأخطاء

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

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

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

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

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

"User verification failed" (403)

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

الحل:

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

"Not enough credits" (403)

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

الحل:

تحقق من الأرصدة عبر /check-user-credits
اشترِ أرصدة إضافية عند الحاجة
استخدم نصوصاً أقصر لاستهلاك أقل

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

"Input text cannot be empty" (400)

السبب: نص فارغ أو مسافات فقط

الحل:

تأكد أن النص غير فارغ
أزل المسافات الزائدة من البداية والنهاية
تحقق من ترميز النص

"Input email is empty" (400)

السبب: بريد إلكتروني مفقود لمعالجة الرابط

الحل:

قدّم بريداً صالحاً عند إرسال عناوين URL
تحقق من تنسيق البريد

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

"Request timeout" (WebSocket)

السبب: تجاوزت معالجة المستند 120 ثانية

الحل:

جرّب نصاً أقصر
تحقق من حمل الخدمة
أعد الطلب

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

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

الحل:

تأكد أن النص يلبي الحد الأدنى
تحقق من التنسيق المدعوم
جرّب نموذجاً آخر
اتصل بالدعم إن استمرت المشكلة

مشاكل اتصال WebSocket

انقطاع الاتصال

السبب: مشكلة شبكة أو انقطاع من الخادم

الحل:

تحقق من الشبكة
نفّذ إعادة اتصال تلقائية
تحقق من صحة رابط WebSocket

"User not found" (WebSocket)

السبب: معرّف مؤسسة غير صالح في اتصال WebSocket

الحل:

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

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

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

اتصل بنا

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

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