Độ trễ gọi cho tài liệu điển hình là bao lâu?

p50 khoảng 600ms cho một lần kiểm tra 500 từ với corpus đã được lập chỉ mục; p95 khoảng 1,8 giây. Thêm khoảng 2 giây nếu bật Layer W (xác minh trực tiếp trên web) — thao tác này sẽ gửi yêu cầu qua Google + Brave. Tài liệu dài (dự kiến xử lý trên 8 giây) sẽ trả về check_id ngay lập tức và phản hồi qua webhook.

Phí API tính như nào?

Mỗi lần POST /v1/checks bị tính phí một lần, không phân biệt số từ, miễn dưới hạn từng gói (1.500 từ Pro, 50.000 Premium, Enterprise tuỳ chỉnh). Thử lại idempotent cùng khoá + nội dung trong 24h không bị tính lại. Lấy kết quả /v1/checks/{id} và gọi phụ trợ SDK là miễn phí.

Tôi có tự host API được không?

Có — github.com/NoplagLabs/noplag-engine là bản tham chiếu Apache-2.0 giống với bản chạy tại engine.noplag.app. docker compose up sẽ cung cấp endpoint /v1/checks cục bộ. Phiên bản cloud bổ sung corpus được quản lý và API key Google/Brave; để tự triển khai hoàn toàn, bạn cần tự cung cấp các khóa này.

Có header thử lại rate-limit đáng tin không?

Gặp 429 chúng tôi trả Retry-After tính bằng giây. Header X-RateLimit-* đi kèm mọi phản hồi — có thể chủ động giảm tải dựa trên X-RateLimit-Remaining, không nhất thiết phải đợi 429. Cả hai đều chính xác, ổn định giữa các bản triển khai.

Chu kỳ phát hành SDK như thế nào?

SDK Python và Node tự đồng bộ từ openapi.yaml mỗi lần engine gắn thẻ. Bản engine lớn (v0.x → v0.y) có SDK cùng ngày. Sửa lỗi nhỏ ra trong tuần. SDK đều theo semver; API chỉ thay đổi lớn khi /v1 → /v2.

Corpus thay đổi giữa tháng thì kiểm tra thế nào?

Mỗi kiểm tra đóng dấu X-Engine-Commit và mốc thời gian corpus. Kiểm lại với corpus mới chỉ cần thêm ?corpus_snapshot=… vào truy vấn. Báo cáo gốc giữ nguyên snapshot — không âm thầm sửa lại điểm tương đồng đã trả trước đó.

Làm sao thử API mà không tốn thêm quota tháng?

Khoá thử nghiệm (nplg_test_…) trỏ vào sandbox: đủ API, không lưu kết quả, không tính giới hạn tháng/rate. Webhook kích hoạt cả từ sandbox, kiểm thử đầu-cuối cũng không tốn quota.

Cách kiểm tra hàng loạt thế nào là đúng?

Gửi song song đến giới hạn tốc độ — có chủ ý không có endpoint batch (gửi 1 lô 500 mà lỗi ở tài liệu 312 còn tệ hơn 500 lần lẻ). Dòng lớn thì ghép webhook: gửi, nhận lại check_id ngay, gửi tiếp 200 cái nữa, xử lý kết quả ngẫu nhiên tới.

Có thể giới hạn kiểm tra cho riêng thư mục của tôi không?

Có — corpora: [] kèm folder_id trong payload sẽ chỉ kiểm tra các thư mục riêng. Có thể kết hợp corpora: ["academic"] để giới hạn cho “học thuật + thư mục riêng”. Giới hạn theo từng lệnh; không phải gói riêng.

Yêu cầu lưu trữ EU hoặc cài on-prem, cần lưu ý gì?

Enterprise có endpoint riêng EU (api.eu.noplag.com) cùng giao diện OpenAPI, đảm bảo dữ liệu cá nhân ở lại EEA. Hoặc tự host bản tham khảo hoàn toàn trong VPC — cùng engine, cùng hợp đồng /v1, không rời khỏi mạng. (Chúng tôi đang chuyển mô hình open-core; các chứng nhận như SOC 2 còn trên lộ trình chứ chưa phát hành — tạm thời chỉ có engine audit.)

RESTOpenAPI 3.0 spec · SDK Python + Node · v0.4.2

Kiểm tra đạo văn API cho tích hợp nhanh

REST endpoint cắm sẵn cho kiểm tra đạo văn + phát hiện AI. OpenAPI 3.0, SDK Python và Node, bản tham khảo Apache 2.0. Từ lệnh curl đầu tiên cho đến webhook khối lượng lớn — cùng engine như noplag.com dùng.

REST · OpenAPI 3.0SDK Python + NodeBản tham khảo Apache 2.0

CUỘC GỌI ĐẦU TIÊN

Từ số 0 đến điểm tương đồng chỉ với một lệnh curl.

POST văn bản, trả về từng đoạn được đánh giá. Không cần SDK, không cần biên dịch, không có định dạng dây chuyền độc quyền.

YÊU CẦU · bashSao chép

$ curl https://engine.noplag.app/v1/checks \    -H "Authorization: Bearer $NOPLAG_KEY" \    -H "Content-Type: application/json" \    -H "Idempotency-Key: $(uuidgen)" \    -d '{        "text": "The rain in Spain falls...",        "corpora": ["web", "academic"],        "ai_detection": true,        "webhook_url": "https://you.example/hook"    }'

PHẢN HỒI · 200 OK · application/jsonSao chép

{  "check_id": "chk_01HX9R2Y4...",  "status": "complete",  "similarity_pct": 23.4,  "ai_score": 0.08,  "engine_commit": "v0.4.2",  "sources": [    { "url": "https://en.wikipedia...",      "matched_chars": 142,      "similarity_pct": 100.0 }  ]}

CÁC ENDPOINT

Bốn endpoint. Một cam kết. Phiên bản trong URL.

Cùng một đặc tả OpenAPI 3.0 được lưu trữ trong kho mã nguồn mở và trên engine.noplag.app. Các SDK được tạo lại từ đặc tả này mỗi khi có bản phát hành được gắn thẻ.

POST/v1/checksGửi kiểm traĐồng bộ tối đa 8 giây; callback webhook nếu lâu hơn. Idempotency-Key bắt buộc.

GET/v1/checks/{id}Lấy kiểm traTrả về trạng thái báo cáo mới nhất. Xem luồng đoạn qua Accept: text/event-stream.

GET/v1/sources/{id}Kiểm tra nguồnXác định nguồn khớp qua ID — URL đầy đủ, ngày snapshot, phân biệt lưu cache hoặc lấy trực tiếp.

POST/v1/foldersQuản lý thư mụcTạo / liệt kê / di chuyển kiểm tra. Giới hạn dò tìm đạo văn cho tài liệu riêng từng thư mục.

POST/v1/webhooksĐăng ký webhookGiao hàng HMAC ký sẵn; retry bậc thang trong 24h; có thể gọi lại từng lần gửi từ dashboard.

Tham khảo đầy đủ tại api./docsopenapi.yaml

XÁC THỰC + GIỚI HẠN TỐC ĐỘ

Token Bearer. Idempotency key. Header giới hạn tốc độ minh bạch.

Không có gì lạ. Tuân thủ chuẩn HTTP — phép thử lại sẵn có vẫn dùng được.

XÁC THỰC

Token Bearer. Một header, không ký nhiều bước.

Tạo khoáDashboard → Cài đặt → API. Khoá có phạm vi (đọc / ghi / quản trị) và thay xoay chỉ hai click.

Gửi khoá trên mỗi lần gọiAuthorization: Bearer nplg_live_…. Khoá thử nghiệm (nplg_test_) trỏ sandbox, không ghi nhận vĩnh viễn.

Gắn Idempotency-Key với POSTUUID nào cũng hợp lệ. Cùng khoá + nội dung trả về phản hồi cache trong 24h, tránh bị tính phí hai lần hoặc lặp kiểm tra khi thử lại.

Authorization: Bearer nplg_live_a82f...Idempotency-Key: 0e8f9c44-...

GIỚI HẠN TỐC ĐỘ

Theo khoá, mỗi phút. Header cho biết tình trạng thực tế.

TẦNGYÊU CẦU/PHÚTHÀNG THÁNGBURST

Miễn phí10100 / tháng20

Pro601.000 / tháng120

Premium30010.000 / tháng600

Doanh nghiệpTuỳ chỉnhThoả thuậnTuỳ chỉnh

X-RateLimit-Limit: 60X-RateLimit-Remaining: 41X-RateLimit-Reset: 1747920480Retry-After: 19  (only on 429)

CÁC SDK

Hai SDK. Sinh từ cùng một spec OpenAPI 3.0.

Python + Node phát hành mỗi lần engine gắn thẻ. Ngôn ngữ khác (Go, Ruby, Java) sinh từ openapi.yaml — chào đón PR cộng đồng.

PYTHONpip install noplag

from noplag import Noplag client = Noplag(api_key="nplg_live_…") report = client.checks.create(    text="...",    corpora=["web", "academic"],    ai_detection=True,) print(report.similarity_pct)

NODEnpm i @noplag/sdk

import Noplag from "@noplag/sdk"; const client = new Noplag({    apiKey: process.env.NOPLAG_KEY,}); const report = await client.checks.create({    text: "...",    corpora: ["web", "academic"],    aiDetection: true,});

<200msđộ trễ p95

99,95%SLA thời gian hoạt động

3vùng (US/EU/AP)

OAPI 3dạng đặc tả

Apache 2.0bản tham khảo

WEBHOOK

Kiểm tra lâu sẽ gọi lại bạn. Có retry không lo failed.

Bốn loại sự kiện. JSON body. HMAC-SHA256 ký trong header.

check.completedBáo cáo đã sẵn · chứa đầy đủ JSON báo cáo

check.failedLỗi vĩnh viễn · có mã lỗi + hướng dẫn thử lại

check.progressTiến trình trung gian · đã khớp nguồn nào cập nhật

folder.sharedThư mục được chia quyền cho đồng đội hoặc kiểm toán ngoài

Retry bậc thang trong 24 giờ. Gửi lại từ dashboard dễ dàng.

Đường cong thử lại5s, 30s, 2m, 10m, 1h, 6h, 24h — sau đó dead-letter

Timeout10s connect, 30s tổng mỗi lần thử

Tiêu chí thành côngPhản hồi HTTP 2xx trong khoảng; chấp nhận cả chuyển hướng

Replay UIChọn lần gửi từ dashboard và gửi lại sang URL khác

Kiểm tra chữ ký. Loại thẳng cái gì sai.

Mọi lần giao hàng đều có X-Noplag-Signature: t=<unix>,v1=<hex>. Tính HMAC-SHA256 trên timestamp + body với bí mật webhook, so sánh hằng thời gian.

h = hmac.new(secret,    f"{t}.{body}".encode(),    hashlib.sha256).hexdigest()assert hmac.compare_digest(h, v1)

NGUYÊN TẮC PHÁT TRIỂN

Chúng tôi tuân thủ HTTP. Đó là toàn bộ tài liệu thiết kế API.

POST là idempotent. Phiên bản trong URL. Lỗi nói rõ cách xử lý tiếp. Header minh bạch về giới hạn tốc độ. Phân trang bằng con trỏ, không offset. Thời gian UTC ISO 8601. Không tự chế HATEOAS, không trả 200 OK với lỗi, không ép dùng OAuth cho máy chủ gọi nhau. Tài liệu thiết kế API là RFC 9110 và đặc tả OpenAPI 3.0 — không có “cách riêng Noplag” nào thêm.

Xem ghi chú thiết kế

HẠN CHẾ THIẾT KẾ

IDEMPCùng Idempotency-Key + nội dung trong 24h trả về phản hồi cache. Thử lại khi lỗi mạng chỉ cần cùng khoá — không bị tính phí hai lần, không lặp kiểm tra.

VERPhiên bản lớn nằm trong URL (/v1, /v2). Đổi lớn gây khác biệt sẽ ra path mới — phiên bản cũ duy trì thêm 12 tháng từ khi công bố.

ERRMọi lỗi 4xx/5xx trả JSON dạng RFC 9457 problem-details. Gồm type, title, detail, instance, và gợi ý noplag.retry_strategy.

PAGPhân trang dựa trên con trỏ ở mọi endpoint danh sách. ?limit=100&cursor=… sẽ trả về next_cursor. Không bị lệch khi chia page như offset.

OBSPhản hồi kèm X-Engine-Commit, X-Request-Id, Server-Timing từng bước. Có thể tra lại kiểm tra qua ID; báo cáo liên kết tới đúng phiên bản engine.

OPENTriển khai tham khảo Apache 2.0 tại github.com/NoplagLabs/noplag-engine. Tự triển khai nếu dữ liệu của bạn không thể rời khỏi hệ thống — giao diện API giống nhau.

FAQ

Câu hỏi thực tế nhóm tích hợp kỹ thuật đặt ra.

Độ trễ gọi cho tài liệu điển hình là bao lâu?: p50 khoảng 600ms cho một lần kiểm tra 500 từ với corpus đã được lập chỉ mục; p95 khoảng 1,8 giây. Thêm khoảng 2 giây nếu bật Layer W (xác minh trực tiếp trên web) — thao tác này sẽ gửi yêu cầu qua Google + Brave. Tài liệu dài (dự kiến xử lý trên 8 giây) sẽ trả về check_id ngay lập tức và phản hồi qua webhook.
Phí API tính như nào?: Mỗi lần POST /v1/checks bị tính phí một lần, không phân biệt số từ, miễn dưới hạn từng gói (1.500 từ Pro, 50.000 Premium, Enterprise tuỳ chỉnh). Thử lại idempotent cùng khoá + nội dung trong 24h không bị tính lại. Lấy kết quả /v1/checks/{id} và gọi phụ trợ SDK là miễn phí.
Tôi có tự host API được không?: Có — github.com/NoplagLabs/noplag-engine là bản tham chiếu Apache-2.0 giống với bản chạy tại engine.noplag.app. docker compose up sẽ cung cấp endpoint /v1/checks cục bộ. Phiên bản cloud bổ sung corpus được quản lý và API key Google/Brave; để tự triển khai hoàn toàn, bạn cần tự cung cấp các khóa này.
Có header thử lại rate-limit đáng tin không?: Gặp 429 chúng tôi trả Retry-After tính bằng giây. Header X-RateLimit-* đi kèm mọi phản hồi — có thể chủ động giảm tải dựa trên X-RateLimit-Remaining, không nhất thiết phải đợi 429. Cả hai đều chính xác, ổn định giữa các bản triển khai.
Chu kỳ phát hành SDK như thế nào?: SDK Python và Node tự đồng bộ từ openapi.yaml mỗi lần engine gắn thẻ. Bản engine lớn (v0.x → v0.y) có SDK cùng ngày. Sửa lỗi nhỏ ra trong tuần. SDK đều theo semver; API chỉ thay đổi lớn khi /v1 → /v2.
Corpus thay đổi giữa tháng thì kiểm tra thế nào?: Mỗi kiểm tra đóng dấu X-Engine-Commit và mốc thời gian corpus. Kiểm lại với corpus mới chỉ cần thêm ?corpus_snapshot=… vào truy vấn. Báo cáo gốc giữ nguyên snapshot — không âm thầm sửa lại điểm tương đồng đã trả trước đó.
Làm sao thử API mà không tốn thêm quota tháng?: Khoá thử nghiệm (nplg_test_…) trỏ vào sandbox: đủ API, không lưu kết quả, không tính giới hạn tháng/rate. Webhook kích hoạt cả từ sandbox, kiểm thử đầu-cuối cũng không tốn quota.
Cách kiểm tra hàng loạt thế nào là đúng?: Gửi song song đến giới hạn tốc độ — có chủ ý không có endpoint batch (gửi 1 lô 500 mà lỗi ở tài liệu 312 còn tệ hơn 500 lần lẻ). Dòng lớn thì ghép webhook: gửi, nhận lại check_id ngay, gửi tiếp 200 cái nữa, xử lý kết quả ngẫu nhiên tới.
Có thể giới hạn kiểm tra cho riêng thư mục của tôi không?: Có — corpora: [] kèm folder_id trong payload sẽ chỉ kiểm tra các thư mục riêng. Có thể kết hợp corpora: ["academic"] để giới hạn cho “học thuật + thư mục riêng”. Giới hạn theo từng lệnh; không phải gói riêng.
Yêu cầu lưu trữ EU hoặc cài on-prem, cần lưu ý gì?: Enterprise có endpoint riêng EU (api.eu.noplag.com) cùng giao diện OpenAPI, đảm bảo dữ liệu cá nhân ở lại EEA. Hoặc tự host bản tham khảo hoàn toàn trong VPC — cùng engine, cùng hợp đồng /v1, không rời khỏi mạng. (Chúng tôi đang chuyển mô hình open-core; các chứng nhận như SOC 2 còn trên lộ trình chứ chưa phát hành — tạm thời chỉ có engine audit.)

Lấy API key. Thực hiện lệnh đầu tiên.

Dùng thử miễn phí 100 lượt API. Tầng Pro $23/tháng cho 1.000 lượt. Có bản Apache 2.0 tham khảo nếu cần giữ tất cả nội bộ.

Lấy API key Xem đặc tả OpenAPI