跳至正文
语言: zh
菜单

Fileverity API 文档

文本检测

通过 POST /text/detections 将纯文本判定为 AI 撰写、混合或人类撰写。内容包括请求和响应字段、段落偏移量、限制与计费。

查看 Markdown更新于 2026-11-04

POST /text/detections 运行一次文本检测。它使用 fvdoc-3-text 对纯文本分类，并返回其中由 AI 撰写的段落。该接口是同步的：结果就在响应中。

示例从文件中读取文本，因此请先把任意一段不少于 100 个词的文字保存为 essay.txt。快速入门中提供了写入示例文本的命令。

curl https://api.fileverity.com/v1/text/detections \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 6b9d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e11" \  -d "$(jq -Rs '{text: ., language: "en"}' essay.txt)"

请求体

字段类型必填说明
textstring是纯文本，至少 100 个词，最多 100,000 个字符。
modelstring否默认值为 fvdoc-3-text。可传入模型 ID 或其快照 ID fvdoc-3-text-2026-11-03。
languagestring 或 null否ISO 639-1 语言代码：en、fr、de、es、zh。省略时自动检测。

未知字段会被拒绝并返回 invalid_parameter。校验至少 100 个词的要求时，汉字约每两个计为一个词。

响应

{  "id": "tdet_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "text.detection",  "created": 1793664000,  "model": "fvdoc-3-text-2026-11-03",  "livemode": true,  "language": "en",  "verdict": "mixed",  "score": 0.97,  "ai_fraction": 0.41,  "segments": [    {      "start": 212,      "end": 433,      "score": 0.97    },    {      "start": 579,      "end": 790,      "score": 0.93    }  ],  "usage": {    "characters": 1412,    "free_characters": 0,    "billed_units": 2  }}
字段类型说明
idstring检测 ID，前缀为 tdet_。
objectstring始终为 text.detection。
createdintegerUnix 时间戳。
modelstring生成该结果的快照。
livemodeboolean测试密钥为 false。
languagestring实际使用的语言：您传入的语言，或自动检测到的语言。
verdictstringai：全文读起来像 AI 撰写。mixed：人类撰写的文本中夹有 AI 撰写的段落。human：未发现 AI 撰写的段落。
scorenumber取值 0 到 1。模型对最像 AI 撰写的段落给出的分数。
ai_fractionnumber取值 0 到 1。被评估文本中落在 AI 撰写段落内的占比。
segmentsarrayAI 撰写的段落。每个段落包含 start、end（不含）和 score。
usageobject已评估的 characters，由免费额度覆盖的 free_characters，以及扣除免费字符后实际计费的 billed_units。

文本检测返回的是统计估计，而不是作者身份的证明。段落边界是近似的。请将其作为人工复核的参考依据之一，不要单独依据它作出影响个人的决定。

段落偏移量

start 和 end 是所提交文本中的偏移量，按 Unicode 码点计数，既不是字节数，也不是 UTF-16 码元数。段落边界是近似的，可能包含相邻的句子。JavaScript 字符串按 UTF-16 索引，因此请先拆分为码点：

const points = Array.from(text);for (const { start, end } of detection.segments) {  console.log(points.slice(start, end).join(""));}

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

计费

  • 文本按每 1,000 字符 US$0.14 计费，按 Unicode 码点计数。每次请求向上取整为整数个计费单位，至少计一个单位。
  • 免费额度中的文本字符会先被使用，并在 usage.free_characters 中报告。usage.billed_units 是扣除它们之后实际计费的单位数，因此费用为 billed_units 乘以 US$0.14。例如：1,412 个字符且已无剩余免费字符时，计 2 个单位，即 US$0.28。
  • 在评估之前被拒绝的请求不收费，例如参数无效、文本过短或过长、语言不受支持等情况。在服务内部失败的检测（service_unavailable）会释放已预留的费用，不收费。
  • 余额不足时返回 insufficient_balance（402）。

存储的内容

文本在评估后即被丢弃，从不存储，因此之后无法再获取。

Fileverity 会保留不含文本的结果（判定、分数、段落偏移量和用量）7 天，以便控制台显示，同时用于用量计费和审计。使用相同 Idempotency-Key 重试的请求，在 24 小时内会得到已保存的结果。文本检测是同步的：它们不会出现在 GET /analyses 中，也不会发送 Webhook 事件。测试密钥不记录任何内容。参见数据保留与安全。

错误

错误码状态原因
text_too_short400少于 100 个词。
text_too_long413超过 100,000 个字符。请把文本拆分为多个请求。
unsupported_language400语言不受支持，或无法检测。
unsupported_media_type415请求体不是以 application/json 发送的。
invalid_json400请求体不是 JSON 对象。
missing_parameter400缺少 text 字段。
invalid_parameter400字段类型错误、发送了未知字段，或 Idempotency-Key 无效。
model_not_found404model 未知。
insufficient_balance402余额不足以支付该请求。
spend_limit_reached402密钥已达到每月支出上限。
idempotency_mismatch, idempotency_in_progress409该 Idempotency-Key 曾用于不同的请求体，或其首次请求仍在运行。
service_unavailable, analysis_failed503, 502检测服务暂时不可用或繁忙。未扣费，请重试。service_unavailable 会带有 retry-after 响应头。

请发送 Idempotency-Key，这样超时后重试就不会重复计费。参见幂等性。