# 文本查重

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

来源： https://fileverity.com/zh/docs/plagiarism

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

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

**请求: cURL**

```bash
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)"
```

**请求: JavaScript**

```javascript
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();
```

**请求: Python**

```python
import os
import uuid
import 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`。

## 响应

**200 OK**

```json
{
  "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 索引，所以请先拆分成码点：

**截取一处重复内容: JavaScript**

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

**截取一处重复内容: Python**

```python
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 的检测模型；参见[数据保留与安全](https://fileverity.com/zh/docs/security.md#retention)。Fileverity 会保留结果（来源、重复位置的偏移量及简短的来源摘录、数量和用量）7 天，以便控制台显示，同时用于用量计费和审计。抓取的页面仅在内存中比对，不会被保存。使用相同 `Idempotency-Key` 重试的请求，在 24 小时内会得到已保存的结果。查重是同步的：它们不会出现在 `GET /analyses` 中，也不会发送 webhook 事件。测试密钥不记录任何内容。参见[数据保留与安全](https://fileverity.com/zh/docs/security.md)。

## 错误

| 错误码 | 状态 | 原因 |
| --- | --- | --- |
| `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`，这样超时后重试就不会重复计费。参见[幂等性](https://fileverity.com/zh/docs/idempotency.md)。

