# 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í.

Nguồn: https://fileverity.com/vi/docs/grammar

`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ụ.

**Yêu cầu: cURL**

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

**Yêu cầu: JavaScript**

```javascript
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();
```

**Yêu cầu: Python**

```python
import os
import uuid
import 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()
```

## Nội dung yêu cầu

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `text` | string | Có | Văn bản thuần túy có ít nhất 20 từ và tối đa 30.000 ký tự. |
| `model` | string | Không | Mặc định `grammar-1`. Chấp nhận mã mô hình hoặc mã snapshot `grammar-1-2026-11-16`. |
| `language` | string hoặc null | Không | Mã 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

**200 OK**

```json
{
  "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ường | Kiểu | Mô tả |
| --- | --- | --- |
| `id` | string | Mã lượt kiểm tra, có tiền tố `tgr_`. |
| `object` | string | Luôn là `text.grammar`. |
| `created` | integer | Dấu thời gian Unix. |
| `model` | string | Snapshot đã tạo ra kết quả. |
| `livemode` | boolean | `false` với khóa thử nghiệm. |
| `language` | string | Ngôn ngữ được dùng: ngôn ngữ bạn đã gửi, hoặc ngôn ngữ được nhận diện. |
| `words` | integer | Số từ trong văn bản. |
| `edits` | array | Cá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. |
| `counts` | object | Số chỉnh sửa theo từng loại: `spelling`, `grammar`, `punctuation`, `word`, `style`. |
| `version` | string | Phiê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. |
| `usage` | object | `characters` đã đánh giá, `billed_units` đã tính phí và `credits` đã trừ. |

> **Lưu ý.** 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 |
| --- | --- |
| `spelling` | Một từ viết sai chính tả. |
| `grammar` | Sự hòa hợp, thì, mạo từ, giới từ, trật tự từ và các lỗi tương tự. |
| `punctuation` | Dấu câu và viết hoa. |
| `word` | Một từ sai hoặc bị dùng nhầm. |
| `style` | Gợ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:

**Tạo văn bản đã sửa: JavaScript**

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

**Tạo văn bản đã sửa: Python**

```python
corrected = text
for edit in reversed(check["edits"]):
    corrected = corrected[: edit["start"]] + edit["replacement"] + corrected[edit["end"] :]
```

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](https://fileverity.com/vi/docs/security.md#retention). 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](https://fileverity.com/vi/docs/security.md).

## Lỗi

| Mã lỗi | Trạng thái | Nguyên nhân |
| --- | --- | --- |
| `text_too_short` | 400 | Ít hơn 20 từ. |
| `text_too_long` | 413 | Hơn 30.000 ký tự. Hãy chia văn bản thành nhiều yêu cầu. |
| `unsupported_language` | 400 | Vă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_type` | 415 | Nội dung yêu cầu không được gửi dưới dạng `application/json`. |
| `invalid_json`, `missing_parameter`, `invalid_parameter` | 400 | Nộ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_found` | 404 | `model` không tồn tại. |
| `plan_required` | 403 | Không gian làm việc chưa mua credit. Hãy mua một gói credit trong Console. |
| `insufficient_balance` | 402 | Số dư không đủ để thanh toán cho yêu cầu. |
| `spend_limit_reached` | 402 | Khóa đã đạt hạn mức chi tiêu hằng tháng. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | `Idempotency-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_failed` | 503, 502 | Dị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`. |

> **Lưu ý.** 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](https://fileverity.com/vi/docs/idempotency.md).

