# Kiểm tra đạo văn

> Tìm các đoạn của một văn bản thuần túy trùng khớp với trang web công khai và Wikipedia bằng POST /text/plagiarism. Các trường yêu cầu và phản hồi, nguồn, đoạn trùng khớp, phần loại trừ, phạm vi, giới hạn và cách tính phí.

Nguồn: https://fileverity.com/vi/docs/plagiarism

`POST /text/plagiarism` kiểm tra một văn bản bằng `plagiarism-1`. Endpoint này tìm trên các trang web công khai và Wikipedia những đoạn trùng khớp với văn bản, rồi trả về các đoạn trùng khớp, nguồn của chúng và tỷ lệ nội dung trùng khớp. Đây là lệnh gọi đồng bộ và thường mất 20 đến 60 giây: hãy giữ kết nối mở.

Hỗ trợ tiếng Anh, tiếng Tây Ban Nha, tiếng Pháp và tiếng Ả Rập. Hãy lưu một văn bản từ 50 từ trở lên thành `essay.txt` để chạy các ví dụ.

**Yêu cầu: 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)"
```

**Yêu cầu: 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();
```

**Yêu cầu: 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()
```

## Nội dung yêu cầu

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `text` | string | Có | Văn bản thuần túy có ít nhất 50 từ và tối đa 30.000 ký tự. |
| `model` | string | Không | Mặc định `plagiarism-1`. Chấp nhận mã mô hình hoặc mã snapshot `plagiarism-1-2026-11-16`. |
| `language` | string hoặc null | Không | Mã ISO 639-1: `en`, `es`, `fr`, `ar`. Tự động nhận diện nếu không truyền. Giá trị này quyết định phiên bản Wikipedia và ngôn ngữ tìm kiếm. |

Các trường không xác định bị từ chối với `invalid_parameter`. Văn bản bằng ngôn ngữ khác, hoặc có ngôn ngữ không nhận diện được, trả về `unsupported_language`.

## Phản hồi

**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
  }
}
```

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `id` | string | Mã lượt kiểm tra, có tiền tố `tpl_`. |
| `object` | string | Luôn là `text.plagiarism`. |
| `created` | integer | Dấu thời gian Unix. |
| `model` | string | Snapshot đã tạo ra kết quả. |
| `livemode` | boolean | `false` với khóa thử nghiệm. |
| `language` | string | Ngôn ngữ được dùng: ngôn ngữ bạn đã gửi, hoặc ngôn ngữ được nhận diện. |
| `words` | integer | Số từ trong văn bản. |
| `scored_words` | integer | Số từ nằm ngoài dấu ngoặc kép và danh mục tài liệu tham khảo. Mẫu số của `similarity`. |
| `excluded_words` | object | `quoted` là số từ trong dấu ngoặc kép và `reference` là số từ trong danh mục tài liệu tham khảo, để bạn có thể tính lại tỷ lệ với các phần loại trừ khác. |
| `matched_words` | integer | Số từ được tính điểm nằm trong các đoạn trùng khớp, mỗi từ chỉ đếm một lần. |
| `similarity` | number | Từ 0 đến 1: `matched_words` chia cho `scored_words`. Là một tỷ lệ nội dung trùng khớp, không phải kết luận. |
| `sources` | array | Các nguồn có ít nhất một đoạn trùng khớp, nguồn lớn nhất xếp đầu. Mỗi nguồn có `id`, `url`, `title`, `host`, `words`, `share` và `partial` (là `true` khi chỉ so sánh được đoạn trích tìm kiếm của trang). |
| `matches` | array | Các đoạn trùng khớp theo thứ tự trong văn bản. Mỗi đoạn có `start`, `end` (không bao gồm), `words`, `source` (`id` của nguồn), `excerpt` (phần văn bản trùng khớp trong nguồn, tối đa 300 ký tự), `quoted`, `reference` và `exact`. |
| `queries` | integer | Số cụm từ đã tìm. |
| `pages` | integer | Số trang đã so sánh. |
| `version` | string | Phiên bản của phương pháp đối chiếu. Chỉ so sánh kết quả trong cùng một phiên bản. |
| `usage` | object | `characters` đã đánh giá, `billed_units` đã tính phí và `credits` đã trừ. |

> **Lưu ý.** Nội dung trùng khớp không phải là kết luận. Phần trích dẫn, cụm từ thông dụng và đoạn đã dẫn nguồn đúng cách cũng sẽ trùng khớp, và tỷ lệ thấp không chứng minh một văn bản là nguyên bản. Hãy hiển thị các đoạn kèm nguồn của chúng cho một người sẽ quyết định dựa trên ngữ cảnh.

## Cách lượt kiểm tra hoạt động và phạm vi của nó

- Các cụm từ đặc trưng của văn bản được tìm dưới dạng cụm từ chính xác trên web công khai và trong phiên bản Wikipedia của ngôn ngữ văn bản đó. Các trang trả về được tải xuống và so sánh với văn bản từng từ một, nên một đoạn trùng khớp cần nhiều từ theo cùng thứ tự; vài từ bị đổi hoặc chèn thêm vẫn trùng khớp, khi đó đoạn được báo cáo với `exact` là `false`.
- Nguồn được tìm kiếm: các trang web công khai và Wikipedia. Sách, tạp chí trả phí, bài của sinh viên khác, nền tảng học tập và cơ sở dữ liệu riêng tư không nằm trong phạm vi của lượt kiểm tra. Các trang từ chối truy cập tự động chỉ được so sánh qua đoạn trích tìm kiếm (`partial`).
- Không tìm thấy: văn bản diễn đạt lại, văn bản đã dịch và văn bản có nguồn không công khai. Một văn bản có thể bị sao chép mà vẫn không có kết quả trùng khớp nào.
- Phần loại trừ: các đoạn trong dấu ngoặc kép có `quoted` là `true`, và các đoạn nằm sau một đề mục như References, Bibliography, Références, Referencias hoặc المراجع có `reference` là `true`. Cả hai đều không được tính vào `similarity`; hãy dùng `excluded_words` để đưa chúng vào.
- Các cụm từ của văn bản được gửi tới Brave Search và Wikipedia để tìm các trang ứng viên. Toàn bộ văn bản không bao giờ được gửi tới họ, và không có gì được thêm vào bất kỳ cơ sở dữ liệu nào.

## Offset

`start` và `end` của mỗi đoạn trùng khớp là offset trong văn bản bạn đã gửi, tính theo code point Unicode, không phải byte và không phải đơn vị UTF-16. Chuỗi JavaScript đánh chỉ số theo UTF-16, nên hãy tách thành các code point trước:

**Cắt một đoạn trùng khớp: JavaScript**

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

**Cắt một đoạn trùng khớp: Python**

```python
for match in check["matches"]:
    print(match["source"], text[match["start"]:match["end"]])
```

## Tính phí

- Một lượt kiểm tra đạo văn có giá 1 credit cho mỗi 1.000 ký tự, đếm theo code point Unicode. Mỗi yêu cầu được làm tròn lên thành số đơn vị nguyên, tối thiểu một đơn vị.
- `usage.billed_units` là số đơn vị đã tính phí và `usage.credits` là số credit đã trừ. Ví dụ: 5.120 ký tự tính thành 6 đơn vị, tức 6 credit.
- Một lượt kiểm tra không tìm thấy nguồn trùng khớp nào vẫn bị tính phí: việc tìm kiếm đã được thực hiện. Các yêu cầu bị từ chối trước khi đánh giá không bị tính phí, và một lượt kiểm tra thất bại bên trong dịch vụ (`service_unavailable`) được hoàn lại và không bị tính phí.
- Không đủ credit sẽ trả về `insufficient_balance` (402). Qua API, kiểm tra đạo văn dành cho các không gian làm việc đã mua credit và luôn dùng credit; trên website và trong Console, lượt kiểm tra này nằm trong gói Pro.

## Dữ liệu được lưu

Một bản sao của văn bản được lưu giữ ở dạng mã hóa tối đa 3 năm để huấn luyện và đánh giá các mô hình phát hiện của Fileverity; xem [Lưu giữ dữ liệu và bảo mật](https://fileverity.com/vi/docs/security.md#retention). Fileverity giữ kết quả (nguồn, offset của đoạn trùng khớp kèm đoạn trích nguồn ngắn, số lượng và mức sử dụng) trong 7 ngày, để Console có thể hiển thị kết quả đó và mức sử dụng có thể được tính phí và đối soát. Các trang đã tải được so sánh trong bộ nhớ và không được lưu giữ. Yêu cầu được gửi lại với cùng `Idempotency-Key` sẽ nhận kết quả đã lưu trong 24 giờ. Lượt kiểm tra đạo văn là đồng bộ: chúng không xuất hiện trong `GET /analyses` và không gửi sự kiện webhook. Khóa thử nghiệm không ghi lại gì. Xem [Lưu giữ dữ liệu và bảo mật](https://fileverity.com/vi/docs/security.md).

## Lỗi

| Mã lỗi | Trạng thái | Nguyên nhân |
| --- | --- | --- |
| `text_too_short` | 400 | Ít hơn 50 từ. |
| `text_too_long` | 413 | Hơn 30.000 ký tự. Hãy chia văn bản thành nhiều yêu cầu. |
| `unsupported_language` | 400 | Văn bản không phải tiếng Anh, tiếng Tây Ban Nha, tiếng Pháp hay tiếng Ả Rập, hoặc không nhận diện được ngôn ngữ. Hãy truyền `language` để chọn một ngôn ngữ. |
| `unsupported_media_type` | 415 | Nội dung yêu cầu không được gửi dưới dạng `application/json`. |
| `invalid_json`, `missing_parameter`, `invalid_parameter` | 400 | Nội dung yêu cầu không phải một đối tượng JSON, thiếu `text`, một trường sai kiểu dữ liệu hoặc có gửi trường không xác định. |
| `model_not_found` | 404 | `model` không tồn tại. |
| `plan_required` | 403 | Không gian làm việc chưa mua credit. Hãy mua một gói credit trong Console. |
| `insufficient_balance` | 402 | Số dư không đủ để thanh toán cho yêu cầu. |
| `spend_limit_reached` | 402 | Khóa đã đạt hạn mức chi tiêu hằng tháng. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | `Idempotency-Key` đã được dùng với nội dung yêu cầu khác, hoặc yêu cầu đầu tiên của khóa này vẫn đang chạy. |
| `service_unavailable`, `analysis_failed` | 503, 502 | Không thể hoàn tất việc tìm kiếm hoặc so sánh. Không bị tính phí; hãy thử lại. `service_unavailable` kèm theo header `retry-after`. |

> **Lưu ý.** Hãy gửi `Idempotency-Key` để việc thử lại sau khi hết thời gian chờ không bị tính phí hai lần. Xem [Idempotency](https://fileverity.com/vi/docs/idempotency.md).

