انتقل إلى المحتوى

توثيق واجهة Fileverity API

التدقيق اللغوي

دقّق نصًا عاديًا لغويًا بحثًا عن الأخطاء الإملائية والنحوية وأخطاء علامات الترقيم واختيار الكلمات عبر POST /text/grammar. حقول الطلب والاستجابة، والفئات، والإزاحات، والحدود، والفوترة.

عرض بصيغة Markdownآخر تحديث: 2026-11-16

يدقّق 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)"

محتوى الطلب

الحقلالنوعمطلوبالوصف
textstringنعمنص عادي لا يقل عن 20 كلمة ولا يزيد على 30,000 حرف.
modelstringلاالافتراضي grammar-1. يقبل معرّف النموذج أو معرّف نسخته المؤرَّخة grammar-1-2026-11-16.
languagestring أو 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  }}
الحقلالنوعالوصف
idstringمعرّف الفحص، بالبادئة tgr_.
objectstringدائمًا text.grammar.
createdintegerطابع زمني بصيغة Unix.
modelstringالنسخة المؤرَّخة التي أنتجت النتيجة.
livemodebooleanfalse لمفاتيح الاختبار.
languagestringاللغة المستخدمة: التي أرسلتها، أو التي اكتُشفت.
wordsintegerعدد الكلمات في النص.
editsarrayالتصحيحات المقترحة بترتيب ورودها في النص. لكل منها start وend (غير مضمَّن في النطاق) وoriginal وreplacement وcategory وmessage. لا تتداخل التعديلات أبدًا.
countsobjectعدد التعديلات في كل فئة: spelling وgrammar وpunctuation وword وstyle.
versionstringإصدار طريقة التدقيق. قارن النتائج داخل الإصدار الواحد فقط.
usageobjectcharacters الأحرف التي جرى تقييمها، و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("");

تُفهرَس سلاسل 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_short400أقل من 20 كلمة.
text_too_long413أكثر من 30,000 حرف. قسّم النص إلى عدة طلبات.
unsupported_language400النص ليس بالعربية أو الإنجليزية أو الفرنسية أو الإسبانية، أو تعذّر التعرف على لغته. أرسل language لاختيار إحداها.
unsupported_media_type415لم يُرسل محتوى الطلب بصيغة application/json.
invalid_json, missing_parameter, invalid_parameter400المحتوى ليس كائن JSON، أو text مفقود، أو نوع أحد الحقول خاطئ، أو أُرسل حقل غير معروف.
model_not_found404قيمة model غير معروفة.
plan_required403لم تشترِ مساحة العمل وحدات رصيد بعد. اشترِ باقة وحدات رصيد من لوحة التحكم.
insufficient_balance402الرصيد لا يغطي الطلب.
spend_limit_reached402بلغ المفتاح حد إنفاقه الشهري.
idempotency_mismatch, idempotency_in_progress409استُخدم Idempotency-Key مع محتوى طلب مختلف، أو لا يزال طلبه الأول قيد التنفيذ.
service_unavailable, analysis_failed503, 502خدمة التدقيق اللغوي غير متاحة مؤقتًا. لا تُحتسب رسوم؛ أعد المحاولة. يحمل service_unavailable ترويسة retry-after.

أرسل Idempotency-Key حتى لا تؤدي إعادة المحاولة بعد انتهاء المهلة إلى احتساب الرسم مرتين. راجع منع التكرار.