跳至正文

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。可传入模型 ID 或其快照 ID 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检查 ID,前缀为 tgr_。
objectstring始终为 text.grammar。
createdintegerUnix 时间戳。
modelstring生成该结果的快照。
livemodeboolean测试密钥为 false。
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 字符 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_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_found404model 未知。
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,这样超时后重试就不会重复计费。参见幂等性。