# 语法检查

> 通过 POST /text/grammar 检查纯文本中的拼写、语法、标点和用词错误。包含请求和响应字段、类别、偏移量、限制与计费。

来源： https://fileverity.com/zh/docs/grammar

`POST /text/grammar` 使用 `grammar-1` 检查一段文本。它返回每条修改建议及其在文本中的位置、类别和简短说明。该接口是同步的：结果就在响应中。

支持英语、西班牙语、法语和阿拉伯语。请把不少于 20 个词的文本保存为 `essay.txt`，以运行示例。

**请求: 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)"
```

**请求: 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();
```

**请求: 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()
```

## 请求体

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `text` | string | 是 | 纯文本，至少 20 个词，最多 30,000 个字符。 |
| `model` | string | 否 | 默认值为 `grammar-1`。可传入模型 ID 或其快照 ID `grammar-1-2026-11-16`。 |
| `language` | string 或 null | 否 | ISO 639-1 语言代码：`en`、`es`、`fr`、`ar`。省略时自动检测；文本混用多种语言时请显式传入。 |

未知字段会被拒绝并返回 `invalid_parameter`。其他语言的文本，或无法识别语言的文本，会返回 `unsupported_language`。

## 响应

**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
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 检查 ID，前缀为 `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`，并从最后一项改到第一项，使前面的偏移量保持有效；也可以先把文本拆分为码点：

**生成修改后的文本: 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("");
```

**生成修改后的文本: Python**

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

Python 字符串本身就按码点索引。

## 计费

- 语法检查每 5,000 字符 1 积分，按 Unicode 码点计数。每次请求向上取整为完整单位，最少一个单位。
- `usage.billed_units` 是计费的单位数，`usage.credits` 是扣除的积分。示例：2,412 个字符计 1 个单位，即 1 积分。
- 在评估之前被拒绝的请求不收费，例如参数无效、文本过短或过长、语言不受支持等情况。在服务内部失败的检测（`service_unavailable`）会释放已预留的费用，不收费。
- 积分不足时返回 `insufficient_balance`（402）。通过 API 使用时，语法检查面向已购买积分的工作区开放，并且始终使用积分；在网站和控制台中，语法检查包含在 Pro 套餐中。

## 存储的内容

文本会在检查期间通过 Vercel AI Gateway 发送给语言模型。文本的副本加密保存，最长 3 年，用于训练和评估 Fileverity 的检测模型；参见[数据保留与安全](https://fileverity.com/zh/docs/security.md#retention)。Fileverity 会保留结果（修改项及其简短的原文和替换片段、数量和用量）7 天，以便控制台显示，同时用于用量计费和审计。使用相同 `Idempotency-Key` 重试的请求，在 24 小时内会得到已保存的结果。语法检查是同步的：它们不会出现在 `GET /analyses` 中，也不会发送 webhook 事件。测试密钥不记录任何内容。参见[数据保留与安全](https://fileverity.com/zh/docs/security.md)。

## 错误

| 错误码 | 状态 | 原因 |
| --- | --- | --- |
| `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`，这样超时后重试就不会重复计费。参见[幂等性](https://fileverity.com/zh/docs/idempotency.md)。

