توثيق واجهة Fileverity API
التدقيق اللغوي
دقّق نصًا عاديًا لغويًا بحثًا عن الأخطاء الإملائية والنحوية وأخطاء علامات الترقيم واختيار الكلمات عبر POST /text/grammar. حقول الطلب والاستجابة، والفئات، والإزاحات، والحدود، والفوترة.
يدقّق POST /text/grammar نصًا واحدًا لغويًا بالنموذج grammar-1. يعيد كل تصحيح مقترح مع موضعه في النص وفئته وشرح موجز. وهو متزامن: النتيجة في الاستجابة نفسها.
يعمل مع العربية والإنجليزية والفرنسية والإسبانية. احفظ نصًا من 20 كلمة أو أكثر باسم essay.txt لتشغيل الأمثلة.
curl https://api.fileverity.com/v1/text/grammar \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 2c7d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e21" \ -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/grammar", { 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" }),});const check = await response.json();import osimport uuidimport requests response = requests.post( "https://api.fileverity.com/v1/text/grammar", headers={ "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4()), }, json={"text": open("essay.txt", encoding="utf-8").read(), "language": "en"},)check = response.json()محتوى الطلب
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
text | string | نعم | نص عادي لا يقل عن 20 كلمة ولا يزيد على 30,000 حرف. |
model | string | لا | الافتراضي grammar-1. يقبل معرّف النموذج أو معرّف نسخته المؤرَّخة grammar-1-2026-11-16. |
language | string أو null | لا | رمز ISO 639-1: en أو es أو fr أو ar. يُكتشف تلقائيًا عند عدم إرساله؛ أرسله عندما يجمع النص بين لغات. |
تُرفض الحقول غير المعروفة برمز الخطأ invalid_parameter. ويُعاد unsupported_language للنص بلغة أخرى أو الذي يتعذّر التعرف على لغته.
الاستجابة
{ "id": "tgr_8Hk2pQ4vN9sL1xR7cW3mY6zB", "object": "text.grammar", "created": 1794787200, "model": "grammar-1-2026-11-16", "livemode": true, "language": "en", "words": 412, "edits": [ { "start": 118, "end": 125, "original": "recieve", "replacement": "receive", "category": "spelling", "message": "The word is spelled receive." }, { "start": 402, "end": 414, "original": "has went", "replacement": "has gone", "category": "grammar", "message": "The past participle of go is gone." }, { "start": 1170, "end": 1175, "original": "Their", "replacement": "They're", "category": "word", "message": "They're is the contraction of they are." }, { "start": 1788, "end": 1789, "original": ",", "replacement": ";", "category": "punctuation", "message": "Two complete sentences are joined with a comma." } ], "counts": { "spelling": 1, "grammar": 1, "punctuation": 1, "word": 1, "style": 0 }, "version": "2026.11-g1", "usage": { "characters": 2412, "billed_units": 1, "credits": 1 }}| الحقل | النوع | الوصف |
|---|---|---|
id | string | معرّف الفحص، بالبادئة tgr_. |
object | string | دائمًا text.grammar. |
created | integer | طابع زمني بصيغة Unix. |
model | string | النسخة المؤرَّخة التي أنتجت النتيجة. |
livemode | boolean | false لمفاتيح الاختبار. |
language | string | اللغة المستخدمة: التي أرسلتها، أو التي اكتُشفت. |
words | integer | عدد الكلمات في النص. |
edits | array | التصحيحات المقترحة بترتيب ورودها في النص. لكل منها start وend (غير مضمَّن في النطاق) وoriginal وreplacement وcategory وmessage. لا تتداخل التعديلات أبدًا. |
counts | object | عدد التعديلات في كل فئة: spelling وgrammar وpunctuation وword وstyle. |
version | string | إصدار طريقة التدقيق. قارن النتائج داخل الإصدار الواحد فقط. |
usage | object | characters الأحرف التي جرى تقييمها، وbilled_units الوحدات المحتسبة، وcredits وحدات رصيد المخصومة. |
تأتي الاقتراحات من نموذج لغوي. قد تكون خاطئة أو غير ضرورية، خاصةً في الأسماء والمصطلحات التقنية والأسلوب المقصود، لذا اعرضها على شخص بوصفها اقتراحات بدلًا من تطبيقها تلقائيًا. التدقيق اللغوي للعربية جديد ولا يزال قيد التقييم.
الفئات
| `category` | المعنى |
|---|---|
spelling | كلمة مكتوبة بخطأ إملائي. |
grammar | المطابقة والزمن وأدوات التعريف وحروف الجر وترتيب الكلمات وما شابه ذلك. |
punctuation | علامات الترقيم والأحرف الكبيرة والصغيرة. |
word | كلمة خاطئة أو مختلطة بأخرى. |
style | اقتراح لتحسين القراءة وليس خطأً. لا يُعاد منه إلا القليل، وفقط حيث تكون الجملة عسيرة القراءة بوضوح. |
تطبيق التعديلات
start وend إزاحتان في النص الذي أرسلته، تُحسبان بنقاط رمز Unicode، وليس بالبايتات ولا بوحدات UTF-16. وoriginal هو النص الواقع بينهما. لبناء النص بعد التصحيح، استبدل كل نطاق بـ replacement مع العمل من آخر تعديل إلى أول تعديل حتى تبقى الإزاحات السابقة صحيحة، أو قسّم النص إلى نقاط رمز أولًا:
const points = Array.from(text);const out = [];let at = 0;for (const edit of check.edits) { out.push(points.slice(at, edit.start).join(""), edit.replacement); at = edit.end;}out.push(points.slice(at).join(""));const corrected = out.join("");corrected = textfor edit in reversed(check["edits"]): corrected = corrected[: edit["start"]] + edit["replacement"] + corrected[edit["end"] :]تُفهرَس سلاسل Python أصلًا بنقاط الترميز.
الفوترة
- تبلغ تكلفة التدقيق اللغوي وحدة رصيد واحدة لكل 5,000 حرف، تُحتسب بنقاط رمز Unicode. يُقرَّب كل طلب إلى وحدات كاملة بالرفع، بحد أدنى وحدة واحدة.
usage.billed_unitsهو عدد الوحدات المحتسبة وusage.creditsوحدات الرصيد المخصومة. مثال: يُحتسب 2,412 حرفًا بوحدة واحدة، أي وحدة رصيد واحدة.- لا تُحتسب رسوم على الطلبات المرفوضة قبل التقييم: المعاملات غير الصالحة، والنص القصير جدًا أو الطويل جدًا، واللغات غير المدعومة وما شابه. وإذا فشل الفحص داخل الخدمة (
service_unavailable) فيُحرَّر المبلغ المحجوز ولا يُحتسب عليك. - عند عدم كفاية وحدات الرصيد يُرجع الطلب
insufficient_balance(402). عبر API يتاح التدقيق اللغوي لمساحات العمل التي اشترت وحدات رصيد، ويستهلك وحدات رصيد دائمًا؛ أما على الموقع وفي لوحة التحكم فهو ضمن خطة Pro.
ما الذي يُخزَّن
يُرسل النص إلى نموذج لغوي عبر Vercel AI Gateway طوال مدة الفحص. وتُحفظ نسخة من النص مشفّرة مدة تصل إلى 3 سنوات لتدريب نماذج الكشف في Fileverity وتقييمها؛ راجع الاحتفاظ بالبيانات والأمان. تحتفظ Fileverity بالنتيجة (التعديلات مع مقتطفاتها القصيرة الأصلية والبديلة، والأعداد، والاستخدام) مدة 7 أيام، حتى تعرضها لوحة التحكم ويمكن احتساب الاستخدام وتدقيقه. ويحصل الطلب المُعاد الذي يحمل Idempotency-Key نفسه على النتيجة المحفوظة خلال 24 ساعة. عمليات التدقيق اللغوي متزامنة: فلا تظهر في GET /analyses ولا تُرسل أحداث Webhook. ولا تسجّل مفاتيح الاختبار شيئًا. راجع الاحتفاظ بالبيانات والأمان.
الأخطاء
| الرمز | الحالة | السبب |
|---|---|---|
text_too_short | 400 | أقل من 20 كلمة. |
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 حتى لا تؤدي إعادة المحاولة بعد انتهاء المهلة إلى احتساب الرسم مرتين. راجع منع التكرار.