توثيق واجهة Fileverity API
فحص الانتحال
اعثر على مقاطع من نص عادي تتطابق مع صفحات الويب العامة وويكيبيديا عبر POST /text/plagiarism. حقول الطلب والاستجابة، والمصادر، والتطابقات، والاستثناءات، والنطاق، والحدود، والفوترة.
يفحص POST /text/plagiarism نصًا واحدًا بالنموذج plagiarism-1. يبحث في صفحات الويب العامة وويكيبيديا عن مقاطع تتطابق مع النص، ويعيد المقاطع المتطابقة والمصادر التي تتطابق معها ونسبة النص المتطابق. وهو متزامن ويستغرق عادةً من 20 إلى 60 ثانية: أبقِ الاتصال مفتوحًا.
يعمل مع العربية والإنجليزية والفرنسية والإسبانية. احفظ نصًا من 50 كلمة أو أكثر باسم essay.txt لتشغيل الأمثلة.
curl https://api.fileverity.com/v1/text/plagiarism \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 3e8d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e31" \ --max-time 120 \ -d "$(jq -Rs '{text: ., language: "en"}' essay.txt)"import { readFile } from "node:fs/promises";import { randomUUID } from "node:crypto"; const response = await fetch("https://api.fileverity.com/v1/text/plagiarism", { method: "POST", headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": randomUUID(), }, body: JSON.stringify({ text: await readFile("essay.txt", "utf8"), language: "en" }), signal: AbortSignal.timeout(120_000),});const check = await response.json();import osimport uuidimport requests response = requests.post( "https://api.fileverity.com/v1/text/plagiarism", headers={ "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4()), }, json={"text": open("essay.txt", encoding="utf-8").read(), "language": "en"}, timeout=120,)check = response.json()محتوى الطلب
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
text | string | نعم | نص عادي لا يقل عن 50 كلمة ولا يزيد على 30,000 حرف. |
model | string | لا | الافتراضي plagiarism-1. يقبل معرّف النموذج أو معرّف نسخته المؤرَّخة plagiarism-1-2026-11-16. |
language | string أو null | لا | رمز ISO 639-1: en أو es أو fr أو ar. يُكتشف تلقائيًا عند عدم إرساله. يحدّد إصدار ويكيبيديا ولغة البحث. |
تُرفض الحقول غير المعروفة برمز الخطأ invalid_parameter. ويُعاد unsupported_language للنص بلغة أخرى أو الذي يتعذّر التعرف على لغته.
الاستجابة
{ "id": "tpl_8Hk2pQ4vN9sL1xR7cW3mY6zB", "object": "text.plagiarism", "created": 1794787200, "model": "plagiarism-1-2026-11-16", "livemode": true, "language": "en", "words": 812, "scored_words": 744, "excluded_words": { "quoted": 23, "reference": 45 }, "matched_words": 61, "similarity": 0.082, "sources": [ { "id": 1, "url": "https://en.wikipedia.org/wiki/Photosynthesis", "title": "Photosynthesis", "host": "en.wikipedia.org", "words": 38, "share": 0.051, "partial": false }, { "id": 2, "url": "https://example.org/biology/light-reactions", "title": "The light reactions of photosynthesis", "host": "example.org", "words": 23, "share": 0.031, "partial": false } ], "matches": [ { "start": 1022, "end": 1288, "words": 38, "source": 1, "excerpt": "Photosynthesis is a system of biological processes by which photopigment-bearing autotrophic organisms, such as most plants, algae and cyanobacteria, convert light energy into the chemical energy necessary to fuel their metabolism.", "quoted": false, "reference": false, "exact": true }, { "start": 2410, "end": 2566, "words": 23, "source": 2, "excerpt": "In the light-dependent reactions, one molecule of the pigment chlorophyll absorbs one photon and loses one electron.", "quoted": false, "reference": false, "exact": false }, { "start": 3105, "end": 3230, "words": 19, "source": 1, "excerpt": "The term photosynthesis usually refers to oxygenic photosynthesis, a process that releases oxygen as a byproduct.", "quoted": true, "reference": false, "exact": true } ], "queries": 12, "pages": 9, "version": "2026.11-p1", "usage": { "characters": 5120, "billed_units": 6, "credits": 6 }}| الحقل | النوع | الوصف |
|---|---|---|
id | string | معرّف الفحص، بالبادئة tpl_. |
object | string | دائمًا text.plagiarism. |
created | integer | طابع زمني بصيغة Unix. |
model | string | النسخة المؤرَّخة التي أنتجت النتيجة. |
livemode | boolean | false لمفاتيح الاختبار. |
language | string | اللغة المستخدمة: التي أرسلتها، أو التي اكتُشفت. |
words | integer | عدد الكلمات في النص. |
scored_words | integer | الكلمات خارج علامات الاقتباس وقائمة المراجع. وهي مقام similarity. |
excluded_words | object | quoted للكلمات داخل علامات الاقتباس وreference للكلمات في قائمة المراجع، لتتمكن من إعادة حساب النسبة باستثناءات أخرى. |
matched_words | integer | الكلمات المحتسبة داخل المقاطع المتطابقة، وتُحسب كل كلمة مرة واحدة. |
similarity | number | من 0 إلى 1: matched_words مقسومًا على scored_words. نسبة من النص المتطابق، وليست حكمًا. |
sources | array | المصادر التي فيها مقطع متطابق واحد على الأقل، من الأكبر إلى الأصغر. لكل مصدر id وurl وtitle وhost وwords وshare وpartial، وقيمته true عندما لم يمكن مقارنة سوى مقتطف البحث من الصفحة. |
matches | array | المقاطع المتطابقة بترتيب ورودها في النص. لكل منها start وend (غير مضمَّن في النطاق) وwords وsource (قيمة id المصدر) وexcerpt (النص المتطابق في المصدر، حتى 300 حرف) وquoted وreference وexact. |
queries | integer | العبارات التي جرى البحث عنها. |
pages | integer | الصفحات التي جرت مقارنتها. |
version | string | إصدار طريقة المطابقة. قارن النتائج داخل الإصدار الواحد فقط. |
usage | object | characters الأحرف التي جرى تقييمها، وbilled_units الوحدات المحتسبة، وcredits وحدات رصيد المخصومة. |
النص المتطابق ليس حكمًا. فالاقتباسات والعبارات الشائعة والمقاطع الموثّقة توثيقًا سليمًا تتطابق أيضًا، ولا تدل نسبة منخفضة على أن النص أصلي. اعرض المقاطع مع مصادرها على شخص يقرّر في سياقها.
كيف يعمل الفحص وما الذي يغطيه
- يُبحث عن عبارات مميزة من النص كعبارات حرفية في الويب العام وفي إصدار ويكيبيديا بلغة النص. وتُجلب الصفحات التي تظهر وتُقارَن بالنص كلمةً كلمة، فيلزم لكل تطابق عدة كلمات بالترتيب نفسه؛ ويظل تغيير بضع كلمات أو إدراجها تطابقًا، ويُبلَّغ عن المقطع حينئذٍ مع
exactبقيمةfalse. - المصادر التي شملها البحث: صفحات الويب العامة وويكيبيديا. لا يطّلع الفحص على الكتب ولا الدوريات العلمية المدفوعة ولا أبحاث الطلاب الآخرين ولا منصات التعلّم ولا قواعد البيانات الخاصة. والصفحات التي ترفض الوصول الآلي تُقارَن عبر مقتطف البحث منها فقط (
partial). - ما لا يُكتشف: النص المُعاد صياغته والنص المترجَم والنص الذي مصدره غير عام. فقد يكون النص منسوخًا ولا يُعثر على أي تطابق.
- الاستثناءات: المقاطع الواقعة بين علامات اقتباس تكون فيها
quotedبقيمةtrue، والمقاطع التي تلي عنوانًا مثل References أو Bibliography أو Références أو Referencias أو المراجع تكون فيهاreferenceبقيمةtrue. ويُستبعد الاثنان منsimilarity؛ استخدمexcluded_wordsلتضمينهما. - تُرسل عبارات من النص إلى Brave Search وإلى ويكيبيديا للعثور على الصفحات المرشَّحة. ولا يُرسل النص كاملًا إليهما أبدًا، ولا يُضاف شيء إلى أي قاعدة بيانات.
الإزاحات
start وend لكل تطابق إزاحتان في النص الذي أرسلته، تُحسبان بنقاط رمز Unicode، وليس بالبايتات ولا بوحدات UTF-16. تفهرس سلاسل JavaScript بوحدات UTF-16، لذا قسّم النص إلى نقاط رمز أولًا:
const points = Array.from(text);for (const { start, end, source } of check.matches) { console.log(source, points.slice(start, end).join(""));}for match in check["matches"]: print(match["source"], text[match["start"]:match["end"]])الفوترة
- تبلغ تكلفة فحص الانتحال وحدة رصيد واحدة لكل 1,000 حرف، تُحتسب بنقاط رمز Unicode. يُقرَّب كل طلب إلى وحدات كاملة بالرفع، بحد أدنى وحدة واحدة.
usage.billed_unitsهو عدد الوحدات المحتسبة وusage.creditsوحدات الرصيد المخصومة. مثال: يُحتسب 5,120 حرفًا بـ 6 وحدات، أي 6 وحدات رصيد.- يُحتسب الفحص الذي لا يجد أي مصدر متطابق أيضًا: فقد أُجري البحث. ولا تُحتسب الطلبات المرفوضة قبل التقييم، ويُلغى حجز وحدات الرصيد للفحص الذي يفشل داخل الخدمة (
service_unavailable) فلا يُحتسب. - عند عدم كفاية وحدات الرصيد يُرجع الطلب
insufficient_balance(402). عبر API يتاح فحص الانتحال لمساحات العمل التي اشترت وحدات رصيد، ويستهلك وحدات رصيد دائمًا؛ أما على الموقع وفي لوحة التحكم فهو ضمن خطة Pro.
ما الذي يُخزَّن
وتُحفظ نسخة من النص مشفّرة مدة تصل إلى 3 سنوات لتدريب نماذج الكشف في Fileverity وتقييمها؛ راجع الاحتفاظ بالبيانات والأمان. تحتفظ Fileverity بالنتيجة (المصادر، وإزاحات التطابقات مع مقتطفات قصيرة من المصادر، والأعداد، والاستخدام) مدة 7 أيام، حتى تعرضها لوحة التحكم ويمكن احتساب الاستخدام وتدقيقه. ولا تُحفظ الصفحات المجلوبة، إذ تُقارَن في الذاكرة. ويحصل الطلب المُعاد الذي يحمل Idempotency-Key نفسه على النتيجة المحفوظة خلال 24 ساعة. عمليات فحص الانتحال متزامنة: فلا تظهر في GET /analyses ولا تُرسل أحداث Webhook. ولا تسجّل مفاتيح الاختبار شيئًا. راجع الاحتفاظ بالبيانات والأمان.
الأخطاء
| الرمز | الحالة | السبب |
|---|---|---|
text_too_short | 400 | أقل من 50 كلمة. |
text_too_long | 413 | أكثر من 30,000 حرف. قسّم النص إلى عدة طلبات. |
unsupported_language | 400 | النص ليس بالعربية أو الإنجليزية أو الفرنسية أو الإسبانية، أو تعذّر التعرف على لغته. أرسل language لاختيار إحداها. |
unsupported_media_type | 415 | لم يُرسل محتوى الطلب بصيغة application/json. |
invalid_json, missing_parameter, invalid_parameter | 400 | المحتوى ليس كائن JSON، أو text مفقود، أو نوع أحد الحقول خاطئ، أو أُرسل حقل غير معروف. |
model_not_found | 404 | قيمة model غير معروفة. |
plan_required | 403 | لم تشترِ مساحة العمل وحدات رصيد بعد. اشترِ باقة وحدات رصيد من لوحة التحكم. |
insufficient_balance | 402 | الرصيد لا يغطي الطلب. |
spend_limit_reached | 402 | بلغ المفتاح حد إنفاقه الشهري. |
idempotency_mismatch, idempotency_in_progress | 409 | استُخدم Idempotency-Key مع محتوى طلب مختلف، أو لا يزال طلبه الأول قيد التنفيذ. |
service_unavailable, analysis_failed | 503, 502 | تعذّر إكمال البحث أو المقارنة. لا تُحتسب رسوم؛ أعد المحاولة. يحمل service_unavailable ترويسة retry-after. |
أرسل Idempotency-Key حتى لا تؤدي إعادة المحاولة بعد انتهاء المهلة إلى احتساب الرسم مرتين. راجع منع التكرار.