Chuyển đến nội dung chính

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.

Xem dạng MarkdownCập nhật 2026-11-04

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ườngKiểuBắt buộcMô tả
modelstringCófvimg-2 hoặc fvdoc-3, hoặc mã snapshot như fvimg-2-2026-10-30.
filestringCóMã của một tệp đã tải lên.
metadataobjectKhôngTố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.passwordstringKhôngMật khẩu của tài liệu được mã hóa, tối đa 256 ký tự.
options.localestringKhôngNgô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"}}'

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ận 202. Header phản hồi preference-applied: wait=N xá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 khi status không còn là processing.
  • Webhook. Đăng ký nhận analysis.completed và analysis.failed rồ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();}
{  "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");}

Trạng thái

Trạng tháiÝ nghĩa
processingLượt phân tích đang chạy. result là null.
succeededKết quả đã sẵn sàng. report_id, report_url, summary và result đều có giá trị.
failedKhô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í.
canceledBạ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ườngMô tả
report_idMã báo cáo, FV-XXXX-XXXX-XXXX.
report_urlTrang 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.
summaryKết luận ngắn gọn. Xem bên dưới.
result.reportBá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_atDấ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.
usageamount đã 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).
metadataMetadata bạn đã gửi, hoặc null.
expires_atDấ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ườngGiá trị
levelL0 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.
actionaccept, review, reject, resubmit
assessmentauthentic_untouched, authentic_locally_edited, ai_generated, undetermined
ailabelled, very_likely, suspected, undecided, low, very_low, not_evaluated
editdetected, suspected, suspected_record, review, generative, minor, none, not_applicable, not_evaluated

Tóm tắt tài liệu

TrườngMô tả
kindLuôn là docpro.
levelL0 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 đề.
actionaccept, 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.
reasonPhá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.
findingsMã của các phát hiện quan trọng.
pages, imagesSố trang của tài liệu và số ảnh nhúng đã kiểm tra.
textKế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á.
strongtrue 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ườngKiểuBắt buộcMô tả
schema"fileverity.report/1"Có
idstringCóMã báo cáo, FV-XXXX-XXXX-XXXX.
sampletrueKhôngCó trong các báo cáo mẫu cố định mà khóa thử nghiệm trả về.
issuedAtstringKhôngThời điểm báo cáo được cấp, theo ISO 8601 ở UTC. Định dạng date-time.
issuerobjectKhôngĐơn vị cấp báo cáo.
fileobjectKhôngẢnh đã được kiểm tra.
proobjectKhôngKết luận. Cùng các giá trị như summary, kèm lý do.
scoreinteger hoặc nullKhô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á.
confidencemột trong "high", "medium", "low"KhôngMứ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.
questionsobjectKhôngBa câu hỏi mà báo cáo trả lời.
generatorobject hoặc nullKhôngCông cụ tạo ảnh AI được nêu cho ảnh này, hoặc null.
regionsmảng objectKhôngCác vùng được đánh dấu, tính bằng điểm ảnh của ảnh được hiển thị.
provenanceobjectKhôngNhữ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.
digeststringKhôngGiá 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ườngKiểuBắt buộcMô tả
schema"fileverity.docpro/1"Có
idstringCóMã báo cáo, FV-XXXX-XXXX-XXXX.
sampletrueKhôngCó trong các báo cáo mẫu cố định mà khóa thử nghiệm trả về.
issuedAtstringKhôngThời điểm báo cáo được cấp, theo ISO 8601 ở UTC. Định dạng date-time.
receivedAtstringKhôngThời điểm nhận tệp, theo ISO 8601 ở UTC. Định dạng date-time.
issuerobjectKhôngĐơn vị cấp báo cáo.
fileobjectKhôngTài liệu đã được kiểm tra.
levelmột trong "L0", "L1", "L2", "L3", "L4", "L5"KhôngMức độ rủi ro, từ L0 đến L5.
actionmột trong "accept", "note", "review", "reject", "resubmit"Không
reasonstring hoặc nullKhôngPhát hiện hoặc điều kiện dẫn đến mức này.
findingsmảng objectKhôngCá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.
textobjectKhôngKết quả cho văn bản của tài liệu.
imagesmảng objectKhôngCác ảnh và hình đồ họa nhúng, được đánh số theo thứ tự trong tài liệu.
structureobject hoặc nullKhôngLịch sử chỉnh sửa của tệp, hoặc null khi chưa được kiểm tra.
provenanceobjectKhôngNhữ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.
digeststringKhôngGiá 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 /analyses liệ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. limit từ 1 đến 100 (mặc định 20), type lọc theo image hoặc document, và starting_after nhận next_cursor của trang trước. Các mục trong danh sách không bao giờ có result.
  • POST /analyses/{id}/cancel hủ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.pdf

Vớ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ỗiTrạng tháiNguyên nhân
file_not_found400Mã 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_found404Mô hình không tồn tại.
invalid_parameter400Mộ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_file415, 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_long413Vượt quá một giới hạn kích thước.
password_required, wrong_password422Tài liệu đã được mã hóa. Hãy gửi options.password.
not_examinable422Tà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_reached402Số 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_failed503, 502Lỗ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_type415Nội dung yêu cầu không được gửi dưới dạng application/json.
idempotency_mismatch, idempotency_in_progress409Idempotency-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_cancelable409Chỉ 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.