Fileverity API 文档
文本查重
通过 POST /text/plagiarism 查找纯文本中与公开网页和维基百科重复的段落。包含请求和响应字段、来源、重复段落、排除项、范围、限制与计费。
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)"import { readFile } from "node:fs/promises";import { randomUUID } from "node:crypto"; const response = await fetch("https://api.fileverity.com/v1/text/plagiarism", { 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" }), signal: AbortSignal.timeout(120_000),});const check = await response.json();import osimport uuidimport requests response = requests.post( "https://api.fileverity.com/v1/text/plagiarism", headers={ "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4()), }, json={"text": open("essay.txt", encoding="utf-8").read(), "language": "en"}, timeout=120,)check = response.json()请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | string | 是 | 纯文本,至少 50 个词,最多 30,000 个字符。 |
model | string | 否 | 默认值为 plagiarism-1。可传入模型 ID 或其快照 ID plagiarism-1-2026-11-16。 |
language | string 或 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 }}| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 检查 ID,前缀为 tpl_。 |
object | string | 始终为 text.plagiarism。 |
created | integer | Unix 时间戳。 |
model | string | 生成该结果的快照。 |
livemode | boolean | 测试密钥为 false。 |
language | string | 实际使用的语言:您传入的语言,或自动检测到的语言。 |
words | integer | 文本中的词数。 |
scored_words | integer | 引号和参考文献之外的词数,即 similarity 的分母。 |
excluded_words | object | quoted 为引号内的词数,reference 为参考文献中的词数,可据此按其他排除方式重新计算占比。 |
matched_words | integer | 重复段落内参与计分的词数,每个词只计一次。 |
similarity | number | 0 到 1:matched_words 除以 scored_words。这是重复文字的占比,不是结论。 |
sources | array | 至少含一个重复段落的来源,按占比从大到小排列。每个来源包含 id、url、title、host、words、share 和 partial,后者为 true 表示只能比对该页面的搜索摘录。 |
matches | array | 按文本顺序排列的重复段落。每段包含 start、end(不含)、words、source(来源的 id)、excerpt(来源中的重复文字,最多 300 个字符)、quoted、reference 和 exact。 |
queries | integer | 已搜索的短语数。 |
pages | integer | 已比对的页面数。 |
version | string | 比对方法的版本。仅在同一版本内比较结果。 |
usage | object | characters 为已评估的字符数,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(""));}for match in check["matches"]: print(match["source"], text[match["start"]:match["end"]])计费
- 查重每 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_short | 400 | 少于 50 个词。 |
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,这样超时后重试就不会重复计费。参见幂等性。