Fileverity API docs
Image detections
Detect whether a whole image was generated by AI with POST /images/detections. One synchronous call: request and response fields, the answer values, limits and billing.
POST /images/detections runs AI image detection. It tells you whether a whole image was generated by AI with vereye-2-detect, using the same models, Content Credentials, AI labels and watermarks as the image verification report (vereye-2), so both give the same answer on AI generation. It is synchronous: the result is in the response.
It does not examine local edits, including AI edits to part of a photo, and it returns no report ID or PDF. For edits, provenance and a record anyone can verify, create an analysis with 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"])Request body
Send the image as multipart/form-data in the field file, up to 4 MB. For larger images, up to 10 MB, upload with POST /files first and send JSON instead:
| Field | Type | Required | Description |
|---|---|---|---|
file | file or string | Yes | The image in a multipart request, or the ID of an uploaded image in a JSON request. JPEG, PNG, WEBP, up to 40 megapixels. A file ID is consumed by the check. |
model | string | No | Default vereye-2-detect. Accepts the model ID or its snapshot ID vereye-2-detect-2026-10-30. |
Unknown fields are rejected with invalid_parameter.
Response
{ "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 }}| Field | Type | Description |
|---|---|---|
id | string | Detection ID, prefixed idet_. |
object | string | Always image.detection. |
created | integer | Unix timestamp. |
model | string | Snapshot that produced the result. |
livemode | boolean | false for test keys. |
verdict | string | ai_generated: the image was generated by AI. no_ai_signs: nothing points to AI generation. inconclusive: the evidence does not decide. |
ai | object | The answer on AI generation, with the same values as questions.ai in the image report. |
generator | object or null | The generator the file declares through Content Credentials, metadata or a watermark, with name and basis. null when the file names none. |
signals | array | The checks behind the answer, each with id and state. See Signals. |
regions | array or null | A coarse grid over the image. Each cell has x, y, w and h in pixels of the displayed image and a level from 0 to 3 for the strength of generation traits. null when the image is too small for a grid. |
candidates | array | Up to three generator families whose pixel traits the image most resembles, each with name and a score from 0 to 1. Empty unless the verdict is ai_generated. |
quality | object or null | How well the file supports analysis: overall, resolution, compression, metadata and distribution, each good, fair or poor. |
limits | array | What limits the result: low_resolution, heavy_compression, platform_copy, no_metadata or models_disagree. |
image | object | width and height as displayed, format, and jpeg_quality, the estimated JPEG quality or null. |
usage | object | credits charged. |
Reading the answer
| `ai.key` | `verdict` | Meaning |
|---|---|---|
labelled | ai_generated | Content Credentials, an AI label or a watermark declare AI generation. ai.basis is verified for trusted credentials, otherwise declared or detected. |
very_likely, suspected | ai_generated | The pixels indicate AI generation, strongly or with some disagreement. |
undecided | inconclusive | The signals are weak or contradict each other. |
low, very_low | no_ai_signs | Nothing in the pixels or metadata points to AI generation. |
ai.strength is strong, moderate or limited and says how strongly the evidence supports the answer. ai.likelihood runs from 0 to 100 in steps of 5, and is null for labelled.
no_ai_signs does not show that a photo is authentic or unedited. AI image detection does not look for edits. When a decision depends on it, run an image verification report and have a person review the result.
Signals
signals lists every check that ran, so you can see what the answer rests on. A state of ai points to AI generation.
| `id` | `state` | Check |
|---|---|---|
model_1, model_2 | ai, unclear, clear, unavailable | Two independently trained models that analyse the pixels. |
credentials | ai, ai_unverified, other, none | Content Credentials (C2PA). ai_unverified: the credentials declare AI generation but their issuer could not be verified. other: credentials are present and declare no AI generation. |
watermark | ai, none, unavailable | Invisible watermarks that open-source generation tools embed in the pixels. |
label | ai, none | A declaration of AI generation in the metadata, such as the IPTC digital source type. |
tool_data | ai, none | Prompts, parameters or generator names saved in the file. |
camera | present, none | Camera make, model and exposure data. It can be edited, and this endpoint does not verify it. |
regions shows where generation traits are strongest. Cells at level 3 carry strong traits. When the verdict is no_ai_signs and some cells are at level 3, part of the image may have been generated or edited with AI: this endpoint does not examine local edits, so run an image verification report.
candidates is an indication, not an identification. It ranks generator families by how closely the pixel traits resemble them, and a generator outside the reference set appears as its nearest match. Rely on generator when the file itself names the tool.
Billing
- AI image detection costs 4 credits per image.
- An image verification report of the same image in the same workspace within 7 days costs 36 credits instead of 40: the detection's credits count toward it once. The analysis reports the charge in
usage.credits. - Requests rejected before evaluation are not charged: invalid parameters, unsupported or damaged files, size limits and similar. A check that fails inside the service (
service_unavailable,analysis_failed) is released and not charged. - Not enough credits return
insufficient_balance(402).
What is stored
The image is examined and deleted. Fileverity keeps the result without the image (verdict, answer, generator, signals, regions, candidates, quality, dimensions, the file's SHA-256 fingerprint and usage) for 7 days, so the Console can show it and usage can be billed and audited. A retried request with the same Idempotency-Key gets the saved result for 24 hours. Image detections are synchronous: they do not appear in GET /analyses and do not send webhook events. Test keys record nothing. See Data retention and security.
Errors
| Code | Status | Cause |
|---|---|---|
missing_parameter | 400 | The file field is missing. |
invalid_parameter | 400 | A field has the wrong type, an unknown field was sent, the model is not an image detection model, or the Idempotency-Key is invalid. |
file_not_found | 400 | The file ID is unknown, expired or already used. |
unsupported_file, invalid_file | 415, 422 | The file is not a JPEG, PNG or WebP image, or it is damaged. |
file_too_large, too_many_pixels | 413 | The multipart file exceeds 4 MB, the uploaded file exceeds 10 MB, or the image exceeds 40 megapixels. |
unsupported_media_type, invalid_json | 415, 400 | The body is neither multipart/form-data nor a JSON object. |
model_not_found | 404 | The model is unknown. |
insufficient_balance, spend_limit_reached | 402 | The balance or the key's monthly limit cannot cover the request. |
idempotency_mismatch, idempotency_in_progress | 409 | The Idempotency-Key was used with a different body, or its first request is still running. |
service_unavailable, analysis_failed | 503, 502 | The detection service is temporarily unavailable or busy. Not charged; retry. service_unavailable carries a retry-after header. |
Send an Idempotency-Key so that retrying after a timeout does not bill twice. See Idempotency.