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

Tài liệu API Fileverity

Bắt đầu nhanh

Tạo không gian làm việc, tạo khóa API và chạy các lượt kiểm tra văn bản và ảnh đầu tiên bằng cURL, JavaScript fetch hoặc Python requests.

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

Trang này hướng dẫn bạn từ bước đăng ký đến kết quả đầu tiên. Bạn cần một tài khoản Fileverity, một terminal có curl và jq, và một tệp JPEG, PNG hoặc WebP cho ví dụ về ảnh.

1. Mở Console

Đăng nhập tại fileverity.com/console bằng mã gửi qua email hoặc Google. Lần đăng nhập đầu tiên sẽ tạo một không gian làm việc cá nhân với số dư trả trước riêng.

Không gian làm việc đầu tiên của bạn có sẵn 5 lượt kiểm tra ảnh hoặc tài liệu miễn phí và 5.000 ký tự văn bản miễn phí. Không cần thẻ. Mỗi người chỉ có một lượt dùng thử miễn phí, và số lượt cho mỗi tên miền email công ty có giới hạn. Đồng nghiệp nên tham gia qua lời mời. Lượt dùng thử miễn phí được dùng trước số dư của bạn. Xem Giá và thanh toán.

2. Tạo khóa API

Mở Khóa API, chọn Tạo khóa, đặt tên cho khóa và chọn chế độ. Hãy tạo khóa Thử nghiệm trước: khóa này trả về kết quả mẫu cố định, không bao giờ gọi mô hình và không bao giờ bị tính phí. Khóa đầy đủ chỉ hiển thị một lần, vì vậy hãy sao chép ngay bây giờ.

Không đưa khóa vào kho mã nguồn hoặc mã chạy trên trình duyệt. Hãy xuất khóa thành biến môi trường:

export FILEVERITY_API_KEY=fv_test_...

3. Xác minh khóa của bạn

GET /models hoạt động với mọi khóa hợp lệ và không bao giờ bị tính phí. Phản hồi 200 liệt kê các mô hình cho biết khóa dùng được. Phản hồi 401 nghĩa là khóa bị thiếu, gõ sai hoặc đã bị thu hồi.

curl -i https://api.fileverity.com/v1/models \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

4. Kiểm tra một đoạn văn bản

Gửi văn bản thuần túy có ít nhất 100 từ tới POST /text/detections. Các ví dụ đọc văn bản từ một tệp, vì vậy trước tiên hãy lưu một đoạn văn bất kỳ có từ 100 từ trở lên thành essay.txt. Lệnh này ghi ra một văn bản mẫu:

cat > essay.txt <<'EOF'Honestly, the delivery was a mess. The driver turned up at six in the evening,the pallet was wet on one side, and nobody at the depot would pick up thephone until Monday. I photographed everything before signing, which is theonly reason we have a leg to stand on. In today's fast-paced logisticslandscape, it is essential for businesses to prioritize reliable deliveryperformance, as timely and undamaged shipments play a pivotal role infostering customer trust and long-term satisfaction. We lost two days. Martarebuilt the schedule by hand and the Leeds order still went out late. Movingforward, it is crucial to implement robust quality assurance measures andestablish clear communication channels, ensuring that all stakeholders remainaligned and that potential issues are proactively addressed. For now I amasking for a credit note and a named contact. Not another apology.EOF
curl https://api.fileverity.com/v1/text/detections \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -d "$(jq -Rs '{text: .}' essay.txt)"

Với khóa thử nghiệm, phản hồi là một kết quả cố định cho văn bản do người viết. Với khóa thật, phản hồi trông như sau:

{  "id": "tdet_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "text.detection",  "created": 1793664000,  "model": "fvdoc-3-text-2026-11-03",  "livemode": true,  "language": "en",  "verdict": "mixed",  "score": 0.97,  "ai_fraction": 0.41,  "segments": [    {      "start": 212,      "end": 433,      "score": 0.97    },    {      "start": 579,      "end": 790,      "score": 0.93    }  ],  "usage": {    "characters": 1412,    "free_characters": 0,    "billed_units": 2  }}

Chi tiết, kể cả cách hoạt động của offset, có trong Phát hiện văn bản.

5. Kiểm tra một ảnh

Ảnh và tài liệu cần hai lệnh gọi: tải tệp lên, rồi tạo một lượt phân tích tham chiếu đến tệp đó. Một lượt phân tích là một lượt kiểm tra ảnh hoặc tài liệu. Prefer: wait=60 giữ yêu cầu cho đến khi có kết quả, tối đa 60 giây.

FILE_ID=$(curl -s https://api.fileverity.com/v1/files \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -F file=@photo.jpg | jq -r .id) curl https://api.fileverity.com/v1/analyses \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -H "Prefer: wait=60" \  -d "{\"model\": \"fvimg-2\", \"file\": \"$FILE_ID\"}"

Một lượt phân tích đã hoàn tất trả về 200 kèm status: succeeded, một summary ngắn và result.report đầy đủ. Nếu hết thời gian chờ trước đó, bạn nhận được 202 kèm status: processing; hãy lấy kết quả sau bằng GET /analyses/{id} hoặc nhận webhook. Xem Lượt phân tích.

{  "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}

Với khóa thử nghiệm, tệp được kiểm tra tính hợp lệ nhưng không được lưu, và lượt phân tích trả về ngay một kết quả mẫu cố định. Mã báo cáo của mẫu này bắt đầu bằng FV-TEST- và không có trang xác minh công khai.

6. Chuyển sang chế độ thật

  • Tạo khóa Thật trong Console và dùng khóa đó thay cho khóa thử nghiệm. Cùng một đoạn mã vẫn chạy mà không cần sửa.
  • Hãy dùng lượt dùng thử miễn phí, hoặc nạp tiền vào số dư không gian làm việc trong Số dư. Số tiền nạp tối thiểu là 19 USD.
  • Hãy đặt hạn mức chi tiêu hằng tháng cho khóa, và thêm một endpoint webhook thay vì truy vấn định kỳ (polling).
  • Hãy gửi Idempotency-Key trong các yêu cầu POST để một lần thử lại không bao giờ chạy cùng một lượt kiểm tra hai lần. Xem Idempotency.

Để biết mỗi loại kiểm tra phân tích những gì và các đội nhóm dùng ở đâu, hãy xem API phát hiện ảnh AI và API phát hiện gian lận tài liệu.

Tiếp theo: Mã mẫu có các chương trình Node.js và Python hoàn chỉnh cho mọi loại kiểm tra và cho webhook. Sau đó hãy đọc Xác thực và khóa API, Lỗi và Tham chiếu API. Nếu có điều gì không hoạt động, hãy gửi email tới hello@fileverity.com hoặc dùng trang liên hệ, kèm mã yêu cầu trong header x-request-id.