Tài liệu API Fileverity
Phân tích
Tạo lượt phân tích ảnh và tài liệu, chờ kết quả bằng Prefer: wait hoặc truy vấn định kỳ, hủy, tải báo cáo PDF và đọc đối tượng báo cáo cùng trang xác minh.
Một lượt phân tích là một lượt kiểm tra ảnh hoặc tài liệu. Lượt phân tích kiểm tra một tệp đã tải lên bằng fvimg-2 (ảnh) hoặc fvdoc-3 (tài liệu). Hãy tải tệp lên trước (xem Tệp), rồi tạo lượt phân tích.
Để xem tổng quan về sản phẩm kèm một yêu cầu và một phản hồi, hãy xem API phát hiện ảnh AI và API phát hiện gian lận tài liệu.
Tạo lượt phân tích
POST /analyses trả về đối tượng lượt phân tích. Khoản phí được tạm giữ khi lượt phân tích được tạo và được hoàn lại nếu lượt phân tích thất bại hoặc bị hủy.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
model | string | Có | fvimg-2 hoặc fvdoc-3, hoặc mã snapshot như fvimg-2-2026-10-30. |
file | string | Có | Mã của một tệp đã tải lên. |
metadata | object | Không | Tối đa 16 cặp chuỗi. Key tối đa 40 ký tự, value tối đa 500. Được trả về trong lượt phân tích và trong webhook. |
options.password | string | Không | Mật khẩu của tài liệu được mã hóa, tối đa 256 ký tự. |
options.locale | string | Không | Ngôn ngữ của các phát hiện về tài liệu: en, fr, de, es, zh, vi hoặc ar. Mặc định là en. |
curl https://api.fileverity.com/v1/analyses \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 0e5f6a64-52c2-4b36-9d0d-6f3d2f4c9a10" \ -d '{"model": "fvdoc-3", "file": "file_Pw3mY6zB8Hk2pQ4vN9sL1xR7", "metadata": {"order_id": "A-10492"}}'const response = await fetch("https://api.fileverity.com/v1/analyses", { method: "POST", headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID(), }, body: JSON.stringify({ model: "fvdoc-3", file: file.id, metadata: { order_id: "A-10492" } }),});const analysis = await response.json();import osimport uuidimport requests response = requests.post( "https://api.fileverity.com/v1/analyses", headers={ "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4()), }, json={"model": "fvdoc-3", "file": file["id"], "metadata": {"order_id": "A-10492"}},)analysis = response.json()Chờ, truy vấn định kỳ hoặc dùng webhook
Yêu cầu tạo trả về 202 kèm status: processing. Bạn có ba cách để nhận kết quả:
- Chờ. Gửi
Prefer: wait=N, trong đó N tối đa là 60 giây. Yêu cầu được giữ cho đến khi lượt phân tích hoàn tất hoặc đã qua N giây. Lượt phân tích đã hoàn tất trả về200; nếu không, bạn vẫn nhận202. Header phản hồipreference-applied: wait=Nxác nhận thời gian chờ đã được áp dụng. - Truy vấn định kỳ. Gọi
GET /analyses/{id}sau mỗi vài giây cho đến khistatuskhông còn làprocessing. - Webhook. Đăng ký nhận
analysis.completedvàanalysis.failedrồi lấy lượt phân tích khi sự kiện đến. Xem Webhook.
let analysis = created;while (analysis.status === "processing") { await new Promise((resolve) => setTimeout(resolve, 3000)); const response = await fetch("https://api.fileverity.com/v1/analyses/" + analysis.id, { headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY }, }); analysis = await response.json();}import time analysis = createdwhile analysis["status"] == "processing": time.sleep(3) analysis = requests.get("https://api.fileverity.com/v1/analyses/" + analysis["id"], headers=headers).json(){ "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB", "object": "analysis", "created": 1793700120, "model": "fvdoc-3-2026-11-03", "livemode": true, "status": "processing", "file": { "name": "contract.pdf", "bytes": 18874368, "format": "pdf" }, "report_id": null, "report_url": null, "summary": null, "result": null, "error": null, "progress": { "stage": "queued", "done": 0, "total": 0, "position": 1 }, "usage": { "amount": 599, "currency": "usd", "funding": "balance" }, "metadata": { "order_id": "A-10492" }, "completed_at": null, "expires_at": null}Trong khi một lượt phân tích đang xử lý, progress.stage là một trong các giá trị queued, reading, analyzing hoặc reporting, và position là vị trí trong hàng đợi khi giai đoạn là queued. Tài liệu có thể phải xếp hàng chờ. Việc chờ kết quả là tùy chọn đối với tài liệu và có thể kết thúc trước khi kết quả sẵn sàng, vì vậy hãy luôn xử lý 202.
Khi dịch vụ đang bận
Khi công suất xử lý đang bận, POST /analyses trả về 503 với mã service_unavailable và header retry-after. Bạn không bị tính phí. Hãy chờ số giây ghi trong retry-after, rồi thử lại với cùng Idempotency-Key để lần thử lại không bao giờ chạy cùng một lượt kiểm tra hai lần. Để đạt thông lượng tốt nhất, hãy chạy các lượt phân tích ảnh lần lượt thay vì song song.
async function create(body, key) { for (let attempt = 0; attempt < 5; attempt++) { const response = await fetch("https://api.fileverity.com/v1/analyses", { method: "POST", headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": key }, body: JSON.stringify(body), }); if (response.status !== 503) return response; const wait = Number(response.headers.get("retry-after")) || 15; await new Promise((resolve) => setTimeout(resolve, wait * 1000)); } throw new Error("Service busy");}import time def create(body, key): for attempt in range(5): response = requests.post("https://api.fileverity.com/v1/analyses", headers={**headers, "Idempotency-Key": key}, json=body) if response.status_code != 503: return response time.sleep(int(response.headers.get("retry-after", 15))) raise RuntimeError("Service busy")Trạng thái
| Trạng thái | Ý nghĩa |
|---|---|
processing | Lượt phân tích đang chạy. result là null. |
succeeded | Kết quả đã sẵn sàng. report_id, report_url, summary và result đều có giá trị. |
failed | Không thể hoàn tất lượt phân tích. error chứa code và message. Bạn không bị tính phí. |
canceled | Bạn đã hủy lượt phân tích. error.code là canceled. Bạn không bị tính phí. |
{ "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB", "object": "analysis", "created": 1793700120, "model": "fvimg-2-2026-10-30", "livemode": true, "status": "failed", "file": { "name": "claim-photo.jpg", "bytes": 2481920, "format": "jpeg" }, "report_id": null, "report_url": null, "summary": null, "result": null, "error": { "code": "analysis_failed", "message": "The analysis could not be completed. You were not charged; retry it, and contact support with the request ID if it fails again." }, "progress": null, "usage": { "amount": 0, "currency": "usd", "funding": null }, "metadata": null, "completed_at": 1793700135, "expires_at": null}Đối tượng báo cáo
Lượt phân tích thành công chứa đúng báo cáo mà website, PDF và trang xác minh hiển thị.
| Trường | Mô tả |
|---|---|
report_id | Mã báo cáo, FV-XXXX-XXXX-XXXX. |
report_url | Trang xác minh công khai của báo cáo. Bất kỳ ai có liên kết đều có thể đối chiếu mã báo cáo, giá trị băm của tệp và dấu thời gian với bản ghi mà không cần tài khoản. |
summary | Kết luận ngắn gọn. Xem bên dưới. |
result.report | Báo cáo đầy đủ. result.report.schema là fileverity.report/1 với ảnh và fileverity.docpro/1 với tài liệu. |
result.stamped_at | Dấu thời gian Unix của dấu thời gian RFC 3161 được cấp cho báo cáo, hoặc null. |
usage | amount đã tính phí, tính bằng cent (bằng 0 với lượt kiểm tra dùng thử miễn phí và lượt thất bại), currency và funding (trial hoặc balance). |
metadata | Metadata bạn đã gửi, hoặc null. |
expires_at | Dấu thời gian Unix mà sau đó result bị xóa. Kết quả được lưu giữ trong 7 ngày. |
{ "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB", "object": "analysis", "created": 1793700120, "model": "fvimg-2-2026-10-30", "livemode": true, "status": "succeeded", "file": { "name": "claim-photo.jpg", "bytes": 2481920, "format": "jpeg" }, "report_id": "FV-7K2M-9QXD-4T8R", "report_url": "https://fileverity.com/verify/FV-7K2M-9QXD-4T8R", "summary": { "level": "L2", "assessment": "authentic_untouched", "action": "accept", "ai": "very_low", "edit": "none" }, "result": { "report": { "schema": "fileverity.report/1", "id": "FV-7K2M-9QXD-4T8R" }, "stamped_at": 1793700130 }, "error": null, "progress": null, "usage": { "amount": 199, "currency": "usd", "funding": "balance" }, "metadata": { "order_id": "A-10492" }, "completed_at": 1793700131, "expires_at": 1794304931}Đối tượng report ở trên đã được rút gọn; đối tượng thật chứa đầy đủ các phát hiện.
summary là kết luận ổn định, ở dạng máy đọc được. result.report là báo cáo đầy đủ mà website và PDF hiển thị. Cấu trúc của báo cáo tuân theo schema được nêu trong result.report.schema. Trong cùng một phiên bản schema, các trường đã liệt kê giữ nguyên tên và ý nghĩa, và có thể bổ sung trường mới, vì vậy hãy bỏ qua các trường bạn không nhận ra.
Tóm tắt ảnh
| Trường | Giá trị |
|---|---|
level | L0 Chưa xác định, L1 Đã xác minh nguồn, L2 Không phát hiện bất thường, L3 Cần xem xét thủ công, L4 Rất đáng ngờ, L5 Bằng chứng mạnh cho thấy ảnh không xác thực. |
action | accept, review, reject, resubmit |
assessment | authentic_untouched, authentic_locally_edited, ai_generated, undetermined |
ai | labelled, very_likely, suspected, undecided, low, very_low, not_evaluated |
edit | detected, suspected, suspected_record, review, generative, minor, none, not_applicable, not_evaluated |
Tóm tắt tài liệu
| Trường | Mô tả |
|---|---|
kind | Luôn là docpro. |
level | L0 Chưa xác định, L1 Nguồn gốc đã xác minh, L2 Không có dấu hiệu can thiệp, L3 Cần xem xét thủ công, L4 Rủi ro cao, L5 Đã xác định có vấn đề. |
action | accept, note (đối chiếu nội dung AI được đánh dấu trong báo cáo với chính sách của bạn), review, reject hoặc resubmit. |
reason | Phát hiện hoặc điều kiện dẫn đến mức này, ví dụ clean, incomplete hoặc mã của một phát hiện, hoặc null. |
findings | Mã của các phát hiện quan trọng. |
pages, images | Số trang của tài liệu và số ảnh nhúng đã kiểm tra. |
text | Kết luận về văn bản của tài liệu (ai_generated, mixed, human, inconclusive), hoặc null khi văn bản không được đánh giá. |
strong | true khi một phát hiện được liệt kê là mạnh. Trường này không xuất hiện trong các trường hợp khác. |
{ "id": "an_Zc4vB7nP1sK8tL3wR6yQm2Xa", "object": "analysis", "created": 1793700300, "model": "fvdoc-3-2026-11-03", "livemode": true, "status": "succeeded", "file": { "name": "contract.pdf", "bytes": 18874368, "format": "pdf" }, "report_id": "FV-3PXH-6WQ2-8NDC", "report_url": "https://fileverity.com/verify/FV-3PXH-6WQ2-8NDC", "summary": { "kind": "docpro", "level": "L3", "action": "review", "reason": null, "findings": [], "pages": 12, "images": 3, "text": "human" }, "result": { "report": { "schema": "fileverity.docpro/1", "id": "FV-3PXH-6WQ2-8NDC" }, "stamped_at": 1793700340 }, "error": null, "progress": null, "usage": { "amount": 599, "currency": "usd", "funding": "balance" }, "metadata": null, "completed_at": 1793700341, "expires_at": 1794305141}Các trường của báo cáo ảnh
result.report của một lượt phân tích ảnh. Các đối tượng lồng nhau được liệt kê trong Tham chiếu API.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
schema | "fileverity.report/1" | Có | |
id | string | Có | Mã báo cáo, FV-XXXX-XXXX-XXXX. |
sample | true | Không | Có trong các báo cáo mẫu cố định mà khóa thử nghiệm trả về. |
issuedAt | string | Không | Thời điểm báo cáo được cấp, theo ISO 8601 ở UTC. Định dạng date-time. |
issuer | object | Không | Đơn vị cấp báo cáo. |
file | object | Không | Ảnh đã được kiểm tra. |
pro | object | Không | Kết luận. Cùng các giá trị như summary, kèm lý do. |
score | integer hoặc null | Không | Điểm xác thực từ 0 đến 100, với bước nhảy 5: bằng chứng ủng hộ mạnh đến đâu việc ảnh là một ảnh chụp xác thực, chưa qua chỉnh sửa. null khi không được đánh giá. |
confidence | một trong "high", "medium", "low" | Không | Mức độ mà tệp này cho phép lượt phân tích xác lập được. Mức tin cậy thấp thường phản ánh chính tệp, chẳng hạn độ phân giải thấp hoặc nén mạnh. |
questions | object | Không | Ba câu hỏi mà báo cáo trả lời. |
generator | object hoặc null | Không | Công cụ tạo ảnh AI được nêu cho ảnh này, hoặc null. |
regions | mảng object | Không | Các vùng được đánh dấu, tính bằng điểm ảnh của ảnh được hiển thị. |
provenance | object | Không | Những gì chính các bản ghi của tệp cho biết về nguồn gốc của tệp. |
digest | string | Không | Giá trị băm của nội dung báo cáo, được trang xác minh sử dụng. |
Các trường của báo cáo tài liệu
result.report của một lượt phân tích tài liệu.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
schema | "fileverity.docpro/1" | Có | |
id | string | Có | Mã báo cáo, FV-XXXX-XXXX-XXXX. |
sample | true | Không | Có trong các báo cáo mẫu cố định mà khóa thử nghiệm trả về. |
issuedAt | string | Không | Thời điểm báo cáo được cấp, theo ISO 8601 ở UTC. Định dạng date-time. |
receivedAt | string | Không | Thời điểm nhận tệp, theo ISO 8601 ở UTC. Định dạng date-time. |
issuer | object | Không | Đơn vị cấp báo cáo. |
file | object | Không | Tài liệu đã được kiểm tra. |
level | một trong "L0", "L1", "L2", "L3", "L4", "L5" | Không | Mức độ rủi ro, từ L0 đến L5. |
action | một trong "accept", "note", "review", "reject", "resubmit" | Không | |
reason | string hoặc null | Không | Phát hiện hoặc điều kiện dẫn đến mức này. |
findings | mảng object | Không | Các phát hiện dẫn đến mức này, mỗi phát hiện kèm các trang và ảnh nhúng mà nó đề cập. |
text | object | Không | Kết quả cho văn bản của tài liệu. |
images | mảng object | Không | Các ảnh và hình đồ họa nhúng, được đánh số theo thứ tự trong tài liệu. |
structure | object hoặc null | Không | Lịch sử chỉnh sửa của tệp, hoặc null khi chưa được kiểm tra. |
provenance | object | Không | Những gì chính các bản ghi của tệp cho biết về nguồn gốc của tệp. |
digest | string | Không | Giá trị băm của nội dung báo cáo, được trang xác minh sử dụng. |
Lấy, liệt kê và hủy
GET /analyses/{id}trả về lượt phân tích, kèm kết quả khi kết quả còn được lưu giữ.GET /analysesliệt kê các lượt phân tích của không gian làm việc, mới nhất trước.limittừ 1 đến 100 (mặc định 20),typelọc theoimagehoặcdocument, vàstarting_afternhậnnext_cursorcủa trang trước. Các mục trong danh sách không bao giờ córesult.POST /analyses/{id}/cancelhủy một lượt phân tích tài liệu đang xử lý và hoàn lại khoản phí đã tạm giữ. Không thể hủy lượt phân tích ảnh; yêu cầu hủy quá muộn hoặc khi lượt phân tích đã hoàn tất sẽ trả vềnot_cancelable.
curl "https://api.fileverity.com/v1/analyses?limit=20&type=document" \ -H "Authorization: Bearer $FILEVERITY_API_KEY" curl -X POST https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/cancel \ -H "Authorization: Bearer $FILEVERITY_API_KEY"Báo cáo PDF
GET /analyses/{id}/report.pdf tải xuống báo cáo PDF có dấu niêm phong của một lượt phân tích thành công khi kết quả còn được lưu giữ. Thêm ?locale= với en, fr, de, es, zh, vi hoặc ar (mặc định en). Gửi header Authorization; phản hồi là application/pdf.
curl "https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/report.pdf?locale=en" \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -o Fileverity-FV-7K2M-9QXD-4T8R.pdfVới tài liệu, ảnh các trang và đoạn trích văn bản được giữ trong 3 giờ sau lượt kiểm tra. Sau đó PDF sẽ không còn chứa chúng, và header phản hồi x-evidence-included có giá trị false. Hãy tải PDF ngay khi lượt phân tích hoàn tất nếu bạn cần PDF bao gồm cả bằng chứng.
Lỗi
| Mã lỗi | Trạng thái | Nguyên nhân |
|---|---|---|
file_not_found | 400 | Mã tệp không tồn tại, đã hết hạn hoặc đã được sử dụng, hoặc quá trình tải lên upload.url chưa hoàn tất. |
model_not_found | 404 | Mô hình không tồn tại. |
invalid_parameter | 400 | Một trường bị thiếu, sai kiểu dữ liệu hoặc không xác định. Các mô hình văn bản dùng với POST /text/detections. |
unsupported_file, invalid_file | 415, 422 | Định dạng tệp không được hỗ trợ cho mô hình này, hoặc tệp bị hỏng. |
file_too_large, too_many_pixels, too_many_pages, document_too_long | 413 | Vượt quá một giới hạn kích thước. |
password_required, wrong_password | 422 | Tài liệu đã được mã hóa. Hãy gửi options.password. |
not_examinable | 422 | Tài liệu không có nội dung nào có thể kiểm tra. Không tính phí. |
insufficient_balance, spend_limit_reached | 402 | Số dư hoặc hạn mức hằng tháng của khóa không đủ để chi trả mức giá này. |
service_unavailable, analysis_failed | 503, 502 | Lỗi tạm thời hoặc công suất xử lý đang bận. Không tính phí; hãy thử lại. service_unavailable có kèm header retry-after. Xem Khi dịch vụ đang bận. |
unsupported_media_type | 415 | Nội dung yêu cầu không được gửi dưới dạng application/json. |
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. Xem Idempotency. |
not_cancelable | 409 | Chỉ có thể hủy lượt phân tích tài liệu vẫn đang được xử lý. |
Một số lỗi xảy ra sau khi lượt phân tích đã được tạo, chẳng hạn khi một mô hình không thể hoàn tất. Các lỗi này đặt status: failed và error cho lượt phân tích thay vì khiến lệnh tạo thất bại, và webhook analysis.failed được kích hoạt. Xem Lỗi.