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。可传入模型 ID 或其快照 ID 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 | 检查 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,并从最后一项改到第一项,使前面的偏移量保持有效;也可以先把文本拆分为码点:
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 字符 1 积分,按 Unicode 码点计数。每次请求向上取整为完整单位,最少一个单位。
usage.billed_units是计费的单位数,usage.credits是扣除的积分。示例:2,412 个字符计 1 个单位,即 1 积分。- 在评估之前被拒绝的请求不收费,例如参数无效、文本过短或过长、语言不受支持等情况。在服务内部失败的检测(
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,这样超时后重试就不会重复计费。参见幂等性。