# 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.

Source: https://fileverity.com/en/docs/image-detections

`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](https://fileverity.com/en/docs/analyses.md) with `vereye-2`.

**Request: cURL**

```bash
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.jpg
```

**Request: JavaScript**

```javascript
import { 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);
```

**Request: Python**

```python
import os
import uuid
import 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`](https://fileverity.com/en/docs/files.md) 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

**200 OK**

```json
{
  "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](https://fileverity.com/en/docs/analyses.md#report-image). |
| `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](#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`.

> **Note.** `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.

> **Note.** `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](https://fileverity.com/en/docs/security.md).

## 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. |

> **Note.** Send an `Idempotency-Key` so that retrying after a timeout does not bill twice. See [Idempotency](https://fileverity.com/en/docs/idempotency.md).

