Tài liệu API Fileverity
Phát hiện ảnh
Phát hiện một ảnh có phải do AI tạo ra hay không bằng POST /images/detections. Một lệnh gọi đồng bộ: các trường yêu cầu và phản hồi, các giá trị trả lời, giới hạn và cách tính phí.
POST /images/detections chạy phát hiện ảnh AI. Endpoint này cho biết toàn bộ ảnh có do AI tạo ra hay không bằng vereye-2-detect, dựa trên cùng các mô hình, Content Credentials, nhãn AI và watermark như báo cáo xác minh ảnh (vereye-2), nên cả hai cho cùng một câu trả lời về nội dung do AI tạo ra. Đây là lệnh gọi đồng bộ: kết quả nằm ngay trong phản hồi.
Endpoint này không kiểm tra chỉnh sửa cục bộ, kể cả việc AI chỉnh sửa một phần của ảnh, và không trả về mã báo cáo hay PDF. Để kiểm tra chỉnh sửa, nguồn gốc và có một bản ghi mà ai cũng có thể xác minh, hãy tạo một lượt phân tích với vereye-2.
curl https://api.fileverity.com/v1/images/detections \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -H "Idempotency-Key: 6b9d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e11" \ -F file=@photo.jpgimport { readFile } from "node:fs/promises";import { randomUUID } from "node:crypto"; const form = new FormData();form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg"); const response = await fetch("https://api.fileverity.com/v1/images/detections", { method: "POST", headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Idempotency-Key": randomUUID() }, body: form,});const detection = await response.json();console.log(detection.verdict, detection.ai);import osimport uuidimport requests response = requests.post( "https://api.fileverity.com/v1/images/detections", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())}, files={"file": open("photo.jpg", "rb")},)detection = response.json()print(detection["verdict"], detection["ai"])Nội dung yêu cầu
Gửi ảnh dưới dạng multipart/form-data trong trường file, tối đa 4 MB. Với ảnh lớn hơn, tối đa 10 MB, hãy tải lên bằng POST /files trước rồi gửi JSON:
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
file | file hoặc string | Có | Ảnh trong yêu cầu multipart, hoặc mã của ảnh đã tải lên trong yêu cầu JSON. JPEG, PNG, WEBP, tối đa 40 megapixel. Mã tệp bị dùng hết sau lượt kiểm tra. |
model | string | Không | Mặc định là vereye-2-detect. Chấp nhận mã mô hình hoặc mã snapshot vereye-2-detect-2026-10-30 của mô hình. |
Các trường không xác định bị từ chối với invalid_parameter.
Phản hồi
{ "id": "idet_8Hk2pQ4vN9sL1xR7cW3mY6zB", "object": "image.detection", "created": 1794096000, "model": "vereye-2-detect-2026-10-30", "livemode": true, "verdict": "ai_generated", "ai": { "key": "very_likely", "basis": "detected", "strength": "strong", "likelihood": 100 }, "generator": null, "signals": [ { "id": "model_1", "state": "ai" }, { "id": "model_2", "state": "ai" }, { "id": "credentials", "state": "none" }, { "id": "watermark", "state": "none" }, { "id": "label", "state": "none" }, { "id": "tool_data", "state": "none" }, { "id": "camera", "state": "none" } ], "regions": [ { "x": 0, "y": 0, "w": 576, "h": 512, "level": 3 }, { "x": 576, "y": 0, "w": 384, "h": 512, "level": 3 }, { "x": 960, "y": 0, "w": 576, "h": 512, "level": 2 }, { "x": 0, "y": 512, "w": 576, "h": 512, "level": 3 }, { "x": 576, "y": 512, "w": 384, "h": 512, "level": 3 }, { "x": 960, "y": 512, "w": 576, "h": 512, "level": 3 } ], "candidates": [ { "name": "Midjourney", "score": 0.65 }, { "name": "OpenAI", "score": 0.25 } ], "quality": { "overall": "fair", "resolution": "good", "compression": "fair", "metadata": "fair", "distribution": "good" }, "limits": [ "no_metadata" ], "image": { "width": 1536, "height": 1024, "format": "jpeg", "jpeg_quality": 85 }, "usage": { "credits": 4 }}| Trường | Kiểu | Mô tả |
|---|---|---|
id | string | Mã lượt phát hiện, có tiền tố idet_. |
object | string | Luôn là image.detection. |
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. |
verdict | string | ai_generated: ảnh do AI tạo ra. no_ai_signs: không có gì cho thấy ảnh do AI tạo ra. inconclusive: bằng chứng chưa đủ để kết luận. |
ai | object | Câu trả lời về nội dung do AI tạo ra, với cùng các giá trị như questions.ai trong báo cáo ảnh. |
generator | object hoặc null | Công cụ tạo ảnh mà tệp khai báo qua Content Credentials, metadata hoặc watermark, kèm name và basis. Là null khi tệp không nêu công cụ nào. |
signals | array | Các bước kiểm tra làm cơ sở cho câu trả lời, mỗi bước có id và state. Xem Tín hiệu. |
regions | mảng hoặc null | Lưới thô phủ lên ảnh. Mỗi ô có x, y, w và h tính bằng điểm ảnh của ảnh hiển thị, cùng level từ 0 đến 3 cho biết mức mạnh của dấu hiệu do AI tạo ra. Là null khi ảnh quá nhỏ để chia lưới. |
candidates | array | Tối đa ba dòng công cụ tạo ảnh có đặc điểm điểm ảnh giống ảnh nhất, mỗi dòng có name và score từ 0 đến 1. Để trống trừ khi kết luận là ai_generated. |
quality | object hoặc null | Mức độ tệp đủ điều kiện để phân tích: overall, resolution, compression, metadata và distribution, mỗi mục là good, fair hoặc poor. |
limits | array | Điều làm hạn chế kết quả: low_resolution, heavy_compression, platform_copy, no_metadata hoặc models_disagree. |
image | object | width và height theo kích thước hiển thị, format, và jpeg_quality là chất lượng JPEG ước tính hoặc null. |
usage | object | credits đã trừ. |
Đọc câu trả lời
| `ai.key` | `verdict` | Ý nghĩa |
|---|---|---|
labelled | ai_generated | Content Credentials, nhãn AI hoặc watermark khai báo ảnh do AI tạo ra. ai.basis là verified với credentials đáng tin cậy, nếu không thì là declared hoặc detected. |
very_likely, suspected | ai_generated | Điểm ảnh cho thấy ảnh do AI tạo ra, ở mức mạnh hoặc còn một số tín hiệu mâu thuẫn. |
undecided | inconclusive | Các tín hiệu yếu hoặc mâu thuẫn với nhau. |
low, very_low | no_ai_signs | Không có gì trong điểm ảnh hay metadata cho thấy ảnh do AI tạo ra. |
ai.strength là strong, moderate hoặc limited và cho biết bằng chứng ủng hộ câu trả lời mạnh đến đâu. ai.likelihood chạy từ 0 đến 100 theo bước 5, và là null với labelled.
no_ai_signs không cho thấy ảnh là xác thực hay chưa bị chỉnh sửa. Phát hiện ảnh AI không tìm dấu hiệu chỉnh sửa. Khi quyết định phụ thuộc vào điều đó, hãy chạy báo cáo xác minh ảnh và nhờ một người xem xét kết quả.
Tín hiệu
signals liệt kê mọi bước kiểm tra đã chạy để bạn biết câu trả lời dựa vào đâu. state là ai nghĩa là bước đó cho thấy ảnh do AI tạo ra.
| `id` | `state` | Bước kiểm tra |
|---|---|---|
model_1, model_2 | ai, unclear, clear, unavailable | Hai mô hình huấn luyện độc lập, cùng phân tích điểm ảnh. |
credentials | ai, ai_unverified, other, none | Content Credentials (C2PA). ai_unverified: Content Credentials khai báo ảnh do AI tạo ra nhưng chưa xác minh được bên ký. other: có Content Credentials và không khai báo AI. |
watermark | ai, none, unavailable | Watermark vô hình mà các công cụ tạo ảnh mã nguồn mở nhúng vào điểm ảnh. |
label | ai, none | Khai báo ảnh do AI tạo ra trong metadata, chẳng hạn loại nguồn số (digital source type) của IPTC. |
tool_data | ai, none | Prompt, tham số hoặc tên công cụ tạo ảnh được lưu trong tệp. |
camera | present, none | Hãng, kiểu máy và thông số phơi sáng của máy ảnh. Dữ liệu này có thể bị chỉnh sửa và endpoint này không xác minh nó. |
regions cho biết dấu hiệu do AI tạo ra mạnh nhất ở đâu. Ô ở mức 3 có dấu hiệu mạnh. Khi kết luận là no_ai_signs mà vẫn có ô ở mức 3, một phần ảnh có thể do AI tạo ra hoặc chỉnh sửa: endpoint này không kiểm tra chỉnh sửa cục bộ, nên hãy chạy báo cáo xác minh ảnh.
candidates chỉ là gợi ý, không phải kết luận về công cụ đã dùng. Danh sách xếp hạng các dòng công cụ theo mức giống nhau về đặc điểm điểm ảnh, và công cụ nằm ngoài tập tham chiếu sẽ hiện là công cụ gần giống nhất. Khi chính tệp nêu tên công cụ, hãy dựa vào generator.
Tính phí
- Phát hiện ảnh AI có giá 4 credit mỗi ảnh.
- Báo cáo xác minh ảnh của cùng ảnh đó trong cùng không gian làm việc trong vòng 7 ngày có giá 36 credit thay vì 40: số credit của lượt phát hiện được tính vào báo cáo một lần. Lượt phân tích báo cáo khoản trừ trong
usage.credits. - Các yêu cầu bị từ chối trước khi đánh giá không bị tính phí: tham số không hợp lệ, tệp không được hỗ trợ hoặc bị hỏng, vượt giới hạn kích thước và các trường hợp tương tự. Lượt kiểm tra thất bại bên trong dịch vụ (
service_unavailable,analysis_failed) được hoàn lại và không bị tính phí. - Không đủ credit sẽ trả về
insufficient_balance(402).
Dữ liệu được lưu
Ảnh được phân tích rồi xóa. Fileverity giữ kết quả mà không kèm ảnh (kết luận, câu trả lời, công cụ tạo ảnh, tín hiệu, vùng, ứng viên, chất lượng, kích thước, giá trị băm SHA-256 của tệp và mức sử dụng) trong 7 ngày, để Console hiển thị được và việc tính phí, đối soát mức sử dụng có căn cứ. Yêu cầu gửi lại với cùng Idempotency-Key nhận lại kết quả đã lưu trong 24 giờ. Lượt phát hiện ảnh là đồng bộ: 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 lưu gì. Xem Lưu giữ dữ liệu và bảo mật.
Lỗi
| Mã lỗi | Trạng thái | Nguyên nhân |
|---|---|---|
missing_parameter | 400 | Thiếu trường file. |
invalid_parameter | 400 | Một trường có kiểu sai, có trường không xác định được gửi lên, mô hình không phải mô hình phát hiện ảnh, hoặc Idempotency-Key không hợp lệ. |
file_not_found | 400 | Mã tệp không tồn tại, đã hết hạn hoặc đã được dùng. |
unsupported_file, invalid_file | 415, 422 | Tệp không phải ảnh JPEG, PNG hoặc WebP, hoặc đã bị hỏng. |
file_too_large, too_many_pixels | 413 | Tệp multipart vượt quá 4 MB, tệp đã tải lên vượt quá 10 MB, hoặc ảnh vượt quá 40 megapixel. |
unsupported_media_type, invalid_json | 415, 400 | Nội dung yêu cầu không phải multipart/form-data cũng không phải một đối tượng JSON. |
model_not_found | 404 | model không tồn tại. |
insufficient_balance, spend_limit_reached | 402 | Số dư hoặc giới hạn hằng tháng của khóa không đủ để chi trả cho yêu cầu. |
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 | Dịch vụ phát hiện tạm thời không khả dụng hoặc đang bận. Không bị tính phí; hãy thử lại. service_unavailable kèm theo header retry-after. |
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.