跳至正文

Fileverity API 文档

文本查重

通过 POST /text/plagiarism 查找纯文本中与公开网页和维基百科重复的段落。包含请求和响应字段、来源、重复段落、排除项、范围、限制与计费。

查看 Markdown更新于 2026-11-16

POST /text/plagiarism 使用 plagiarism-1 检查一段文本。它在公开网页和维基百科中搜索与文本重复的段落,返回重复段落、对应来源和重复文字占比。该接口是同步的,通常需要 20 至 60 秒:请保持连接打开。

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

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

请求体

字段类型必填说明
textstring是纯文本,至少 50 个词,最多 30,000 个字符。
modelstring否默认值为 plagiarism-1。可传入模型 ID 或其快照 ID plagiarism-1-2026-11-16。
languagestring 或 null否ISO 639-1 语言代码:en、es、fr、ar。省略时自动检测。它决定使用哪个语言版本的维基百科,以及搜索所用的语言。

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

响应

{  "id": "tpl_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "text.plagiarism",  "created": 1794787200,  "model": "plagiarism-1-2026-11-16",  "livemode": true,  "language": "en",  "words": 812,  "scored_words": 744,  "excluded_words": {    "quoted": 23,    "reference": 45  },  "matched_words": 61,  "similarity": 0.082,  "sources": [    {      "id": 1,      "url": "https://en.wikipedia.org/wiki/Photosynthesis",      "title": "Photosynthesis",      "host": "en.wikipedia.org",      "words": 38,      "share": 0.051,      "partial": false    },    {      "id": 2,      "url": "https://example.org/biology/light-reactions",      "title": "The light reactions of photosynthesis",      "host": "example.org",      "words": 23,      "share": 0.031,      "partial": false    }  ],  "matches": [    {      "start": 1022,      "end": 1288,      "words": 38,      "source": 1,      "excerpt": "Photosynthesis is a system of biological processes by which photopigment-bearing autotrophic organisms, such as most plants, algae and cyanobacteria, convert light energy into the chemical energy necessary to fuel their metabolism.",      "quoted": false,      "reference": false,      "exact": true    },    {      "start": 2410,      "end": 2566,      "words": 23,      "source": 2,      "excerpt": "In the light-dependent reactions, one molecule of the pigment chlorophyll absorbs one photon and loses one electron.",      "quoted": false,      "reference": false,      "exact": false    },    {      "start": 3105,      "end": 3230,      "words": 19,      "source": 1,      "excerpt": "The term photosynthesis usually refers to oxygenic photosynthesis, a process that releases oxygen as a byproduct.",      "quoted": true,      "reference": false,      "exact": true    }  ],  "queries": 12,  "pages": 9,  "version": "2026.11-p1",  "usage": {    "characters": 5120,    "billed_units": 6,    "credits": 6  }}
字段类型说明
idstring检查 ID,前缀为 tpl_。
objectstring始终为 text.plagiarism。
createdintegerUnix 时间戳。
modelstring生成该结果的快照。
livemodeboolean测试密钥为 false。
languagestring实际使用的语言:您传入的语言,或自动检测到的语言。
wordsinteger文本中的词数。
scored_wordsinteger引号和参考文献之外的词数,即 similarity 的分母。
excluded_wordsobjectquoted 为引号内的词数,reference 为参考文献中的词数,可据此按其他排除方式重新计算占比。
matched_wordsinteger重复段落内参与计分的词数,每个词只计一次。
similaritynumber0 到 1:matched_words 除以 scored_words。这是重复文字的占比,不是结论。
sourcesarray至少含一个重复段落的来源,按占比从大到小排列。每个来源包含 id、url、title、host、words、share 和 partial,后者为 true 表示只能比对该页面的搜索摘录。
matchesarray按文本顺序排列的重复段落。每段包含 start、end(不含)、words、source(来源的 id)、excerpt(来源中的重复文字,最多 300 个字符)、quoted、reference 和 exact。
queriesinteger已搜索的短语数。
pagesinteger已比对的页面数。
versionstring比对方法的版本。仅在同一版本内比较结果。
usageobjectcharacters 为已评估的字符数,billed_units 为计费单位数,credits 为扣除的积分。

重复文字不是结论。引文、常见表述和已规范标注的引用同样会重复,占比低也不能说明文本是原创的。请把重复段落连同来源一并交给用户,由其结合上下文判断。

检测原理与覆盖范围

  • 文本中有区分度的短语会作为精确短语,在公开网络和该文本语言对应的维基百科版本中搜索。返回的页面会被抓取,并与文本逐词比对,因此一处重复需要连续多个词按相同顺序出现;个别词被改动或插入时仍会命中,此时该段落的 exact 为 false。
  • 搜索范围:公开网页和维基百科。本检测无法查看图书、付费期刊、其他学生的论文、学习平台和私有数据库。拒绝自动访问的页面只能通过其搜索摘录比对(partial)。
  • 查不到的内容:改写后的文本、翻译后的文本,以及来源不公开的文本。文本即使是抄来的,也可能查不到任何重复。
  • 排除项:引号内的段落,其 quoted 为 true;位于 References、Bibliography、Références、Referencias 或 المراجع 等标题之后的段落,其 reference 为 true。两者都不计入 similarity;如需将其计入,请使用 excluded_words。
  • 文本中的短语会发送给 Brave Search 和维基百科,用于查找候选页面。全文不会发送给它们,也不会被添加到任何数据库。

偏移量

每处重复的 start 和 end 是相对于您提交的文本的偏移量,按 Unicode 码点计数,不是字节,也不是 UTF-16 单元。JavaScript 字符串按 UTF-16 索引,所以请先拆分成码点:

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

计费

  • 查重每 1,000 字符 1 积分,按 Unicode 码点计数。每次请求向上取整为完整单位,最少一个单位。
  • usage.billed_units 是计费的单位数,usage.credits 是扣除的积分。示例:5,120 个字符计 6 个单位,即 6 积分。
  • 未找到任何重复来源的检查同样收费:搜索已经执行。评估前即被拒绝的请求不收费;在服务内部失败的检查(service_unavailable)会释放已预留的费用,不收费。
  • 积分不足时返回 insufficient_balance(402)。通过 API 使用时,查重面向已购买积分的工作区开放,并且始终使用积分;在网站和控制台中,查重包含在 Pro 套餐中。

存储的内容

文本的副本加密保存,最长 3 年,用于训练和评估 Fileverity 的检测模型;参见数据保留与安全。Fileverity 会保留结果(来源、重复位置的偏移量及简短的来源摘录、数量和用量)7 天,以便控制台显示,同时用于用量计费和审计。抓取的页面仅在内存中比对,不会被保存。使用相同 Idempotency-Key 重试的请求,在 24 小时内会得到已保存的结果。查重是同步的:它们不会出现在 GET /analyses 中,也不会发送 webhook 事件。测试密钥不记录任何内容。参见数据保留与安全。

错误

错误码状态原因
text_too_short400少于 50 个词。
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,这样超时后重试就不会重复计费。参见幂等性。