Chuyển đến nội dung chính

Tài liệu API Fileverity

Kiểm tra ngữ pháp

Kiểm tra lỗi chính tả, ngữ pháp, dấu câu và dùng từ trong văn bản thuần túy bằng POST /text/grammar. Các trường yêu cầu và phản hồi, loại lỗi, offset, giới hạn và cách tính phí.

Xem dạng MarkdownCập nhật 2026-11-16

POST /text/grammar kiểm tra một văn bản bằng grammar-1. Endpoint này trả về mọi chỉnh sửa được đề xuất kèm vị trí trong văn bản, loại lỗi và một lời giải thích ngắn. Đây là lệnh gọi đồng bộ: kết quả nằm ngay trong phản hồi.

Hỗ trợ tiếng Anh, tiếng Tây Ban Nha, tiếng Pháp và tiếng Ả Rập. Hãy lưu một văn bản từ 20 từ trở lên thành essay.txt để chạy các ví dụ.

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)"

Nội dung yêu cầu

TrườngKiểuBắt buộcMô tả
textstringCóVăn bản thuần túy có ít nhất 20 từ và tối đa 30.000 ký tự.
modelstringKhôngMặc định grammar-1. Chấp nhận mã mô hình hoặc mã snapshot grammar-1-2026-11-16.
languagestring hoặc nullKhôngMã ISO 639-1: en, es, fr, ar. Tự động nhận diện nếu không truyền; hãy truyền khi văn bản trộn nhiều ngôn ngữ.

Các trường không xác định bị từ chối với invalid_parameter. Văn bản bằng ngôn ngữ khác, hoặc có ngôn ngữ không nhận diện được, trả về unsupported_language.

Phản hồi

{  "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  }}
TrườngKiểuMô tả
idstringMã lượt kiểm tra, có tiền tố tgr_.
objectstringLuôn là text.grammar.
createdintegerDấu thời gian Unix.
modelstringSnapshot đã tạo ra kết quả.
livemodebooleanfalse với khóa thử nghiệm.
languagestringNgôn ngữ được dùng: ngôn ngữ bạn đã gửi, hoặc ngôn ngữ được nhận diện.
wordsintegerSố từ trong văn bản.
editsarrayCác chỉnh sửa được đề xuất theo thứ tự trong văn bản. Mỗi chỉnh sửa có start, end (không bao gồm), original, replacement, category và message. Các chỉnh sửa không bao giờ chồng lên nhau.
countsobjectSố chỉnh sửa theo từng loại: spelling, grammar, punctuation, word, style.
versionstringPhiên bản của phương pháp soát lỗi. Chỉ so sánh kết quả trong cùng một phiên bản.
usageobjectcharacters đã đánh giá, billed_units đã tính phí và credits đã trừ.

Các gợi ý do mô hình ngôn ngữ đưa ra. Chúng có thể sai hoặc không cần thiết, đặc biệt với tên riêng, thuật ngữ chuyên ngành và văn phong có chủ ý, vì vậy hãy hiển thị cho người dùng như các gợi ý thay vì áp dụng âm thầm. Kiểm tra tiếng Ả Rập còn mới và vẫn đang được đánh giá.

Các loại lỗi

`category`Ý nghĩa
spellingMột từ viết sai chính tả.
grammarSự hòa hợp, thì, mạo từ, giới từ, trật tự từ và các lỗi tương tự.
punctuationDấu câu và viết hoa.
wordMột từ sai hoặc bị dùng nhầm.
styleGợi ý về khả năng đọc hiểu chứ không phải lỗi. Chỉ trả về một vài gợi ý, và chỉ khi một câu thực sự khó đọc.

Áp dụng các chỉnh sửa

start và end là offset trong văn bản bạn đã gửi, tính theo code point Unicode, không phải byte và không phải đơn vị UTF-16. original là phần văn bản nằm giữa hai vị trí đó. Để tạo văn bản đã sửa, hãy thay từng khoảng bằng replacement, đi từ chỉnh sửa cuối cùng về đầu để các offset phía trước vẫn đúng, hoặc tách văn bản thành các code point trước:

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("");

Chuỗi trong Python vốn đã được đánh chỉ mục theo code point.

Tính phí

  • Một lượt kiểm tra ngữ pháp có giá 1 credit cho mỗi 5.000 ký tự, đếm theo code point Unicode. Mỗi yêu cầu được làm tròn lên thành số đơn vị nguyên, tối thiểu một đơn vị.
  • usage.billed_units là số đơn vị đã tính phí và usage.credits là số credit đã trừ. Ví dụ: 2.412 ký tự tính thành 1 đơn vị, tức 1 credit.
  • Các yêu cầu bị từ chối trước khi đánh giá không bị tính phí: tham số không hợp lệ, văn bản quá ngắn hoặc quá dài, ngôn ngữ không được hỗ trợ và các trường hợp tương tự. Lượt kiểm tra thất bại bên trong dịch vụ (service_unavailable) được hoàn lại và không bị tính phí.
  • Không đủ credit sẽ trả về insufficient_balance (402). Qua API, kiểm tra ngữ pháp dành cho các không gian làm việc đã mua credit và luôn dùng credit; trên website và trong Console, lượt kiểm tra này nằm trong gói Pro.

Dữ liệu được lưu

Văn bản được gửi tới một mô hình ngôn ngữ qua Vercel AI Gateway trong suốt thời gian kiểm tra. Một bản sao của văn bản được lưu giữ ở dạng mã hóa tối đa 3 năm để huấn luyện và đánh giá các mô hình phát hiện của Fileverity; xem Lưu giữ dữ liệu và bảo mật. Fileverity giữ kết quả (các chỉnh sửa cùng đoạn gốc và đoạn thay thế ngắn, số lượng và mức sử dụng) trong 7 ngày, để Console có thể hiển thị kết quả đó và mức sử dụng có thể được tính phí và đối soát. Yêu cầu được gửi lại với cùng Idempotency-Key sẽ nhận kết quả đã lưu trong 24 giờ. Lượt kiểm tra ngữ pháp là đồng bộ: chúng không xuất hiện trong GET /analyses và không gửi sự kiện webhook. Khóa thử nghiệm không ghi lại gì. Xem Lưu giữ dữ liệu và bảo mật.

Lỗi

Mã lỗiTrạng tháiNguyên nhân
text_too_short400Ít hơn 20 từ.
text_too_long413Hơn 30.000 ký tự. Hãy chia văn bản thành nhiều yêu cầu.
unsupported_language400Văn bản không phải tiếng Anh, tiếng Tây Ban Nha, tiếng Pháp hay tiếng Ả Rập, hoặc không nhận diện được ngôn ngữ. Hãy truyền language để chọn một ngôn ngữ.
unsupported_media_type415Nội dung yêu cầu không được gửi dưới dạng application/json.
invalid_json, missing_parameter, invalid_parameter400Nội dung yêu cầu không phải một đối tượng JSON, thiếu text, một trường sai kiểu dữ liệu hoặc có gửi trường không xác định.
model_not_found404model không tồn tại.
plan_required403Không gian làm việc chưa mua credit. Hãy mua một gói credit trong Console.
insufficient_balance402Số dư không đủ để thanh toán cho yêu cầu.
spend_limit_reached402Khóa đã đạt hạn mức chi tiêu hằng tháng.
idempotency_mismatch, idempotency_in_progress409Idempotency-Key đã được dùng với nội dung yêu cầu khác, hoặc yêu cầu đầu tiên của khóa này vẫn đang chạy.
service_unavailable, analysis_failed503, 502Dịch vụ kiểm tra ngữ pháp tạm thời không khả dụng. Không bị tính phí; hãy thử lại. service_unavailable kèm theo header retry-after.

Hãy gửi Idempotency-Key để việc thử lại sau khi hết thời gian chờ không bị tính phí hai lần. Xem Idempotency.