# Bilderkennungen

> Mit POST /images/detections erkennen Sie, ob ein ganzes Bild mit KI erzeugt wurde. Ein synchroner Aufruf: Felder von Anfrage und Antwort, Antwortwerte, Limits und Abrechnung.

Quelle: https://fileverity.com/de/docs/image-detections

`POST /images/detections` führt die KI-Erkennung für Bilder aus. Mit `vereye-2-detect` sagt sie Ihnen, ob ein ganzes Bild mit KI erzeugt wurde, auf Basis derselben Modelle, Content Credentials, KI-Kennzeichnungen und Wasserzeichen wie der Bildforensik-Bericht (`vereye-2`); beide geben daher dieselbe Antwort zur KI-Erzeugung. Der Aufruf ist synchron: Das Ergebnis steht in der Antwort.

Lokale Bearbeitungen, auch KI-Änderungen an einem Teil eines Fotos, werden nicht untersucht, und es gibt weder Berichts-ID noch PDF. Für Bearbeitungen, Herkunft und einen Nachweis, den jeder verifizieren kann, erstellen Sie eine [Analyse](https://fileverity.com/de/docs/analyses.md) mit `vereye-2`.

**Anfrage: 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
```

**Anfrage: 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);
```

**Anfrage: 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"])
```

## Anfragetext

Senden Sie das Bild als `multipart/form-data` im Feld `file`, bis zu 4 MB. Größere Bilder, bis zu 10 MB, laden Sie zuerst mit [`POST /files`](https://fileverity.com/de/docs/files.md) hoch und senden dann JSON:

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `file` | file oder string | Ja | Das Bild in einer Multipart-Anfrage oder die ID eines hochgeladenen Bildes in einer JSON-Anfrage. JPEG, PNG, WEBP, bis 40 Megapixel. Eine Datei-ID wird durch die Prüfung verbraucht. |
| `model` | string | Nein | Standard `vereye-2-detect`. Akzeptiert die Modell-ID oder ihre Snapshot-ID `vereye-2-detect-2026-10-30`. |

Unbekannte Felder werden mit `invalid_parameter` abgelehnt.

## Antwort

**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
  }
}
```

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `id` | string | ID der Bilderkennung mit dem Präfix `idet_`. |
| `object` | string | Immer `image.detection`. |
| `created` | integer | Unix-Zeitstempel. |
| `model` | string | Snapshot, der das Ergebnis erzeugt hat. |
| `livemode` | boolean | `false` bei Testschlüsseln. |
| `verdict` | string | `ai_generated`: Das Bild wurde mit KI erzeugt. `no_ai_signs`: Nichts deutet auf KI-Erzeugung hin. `inconclusive`: Die Belege reichen für eine Entscheidung nicht aus. |
| `ai` | object | Die Antwort zur KI-Erzeugung, mit denselben Werten wie `questions.ai` im [Bildbericht](https://fileverity.com/de/docs/analyses.md#report-image). |
| `generator` | object oder null | Der Generator, den die Datei über Content Credentials, Metadaten oder ein Wasserzeichen angibt, mit `name` und `basis`. `null`, wenn die Datei keinen nennt. |
| `signals` | array | Die Prüfungen hinter der Antwort, jeweils mit `id` und `state`. Siehe [Signale](#signals). |
| `regions` | Array oder null | Ein grobes Raster über dem Bild. Jede Zelle hat `x`, `y`, `w` und `h` in Pixeln des angezeigten Bildes sowie ein `level` von 0 bis 3 für die Stärke der Generierungsmerkmale. `null`, wenn das Bild für ein Raster zu klein ist. |
| `candidates` | array | Bis zu drei Generatorfamilien, deren Pixelmerkmalen das Bild am ähnlichsten ist, jeweils mit `name` und einem `score` von 0 bis 1. Leer, außer die Einstufung ist `ai_generated`. |
| `quality` | object oder null | Wie gut sich die Datei analysieren lässt: `overall`, `resolution`, `compression`, `metadata` und `distribution`, jeweils `good`, `fair` oder `poor`. |
| `limits` | array | Was das Ergebnis einschränkt: `low_resolution`, `heavy_compression`, `platform_copy`, `no_metadata` oder `models_disagree`. |
| `image` | object | `width` und `height` wie angezeigt, `format` und `jpeg_quality`, die geschätzte JPEG-Qualität oder `null`. |
| `usage` | object | Belastete `credits`. |

## Die Antwort lesen

| `ai.key` | `verdict` | Bedeutung |
| --- | --- | --- |
| `labelled` | `ai_generated` | Content Credentials, eine KI-Kennzeichnung oder ein Wasserzeichen weisen auf KI-Erzeugung hin. `ai.basis` ist `verified` bei vertrauenswürdigen Credentials, sonst `declared` oder `detected`. |
| `very_likely`, `suspected` | `ai_generated` | Die Pixel deuten auf KI-Erzeugung hin, deutlich oder mit gewissen Widersprüchen. |
| `undecided` | `inconclusive` | Die Signale sind schwach oder widersprechen sich. |
| `low`, `very_low` | `no_ai_signs` | Weder die Pixel noch die Metadaten deuten auf KI-Erzeugung hin. |

`ai.strength` ist `strong`, `moderate` oder `limited` und gibt an, wie stark die Belege die Antwort stützen. `ai.likelihood` reicht in Schritten von 5 von 0 bis 100 und ist bei `labelled` `null`.

> **Hinweis.** `no_ai_signs` zeigt nicht, dass ein Foto echt oder unbearbeitet ist. Die KI-Erkennung für Bilder sucht nicht nach Bearbeitungen. Hängt eine Entscheidung davon ab, führen Sie einen Bildforensik-Bericht aus und lassen Sie das Ergebnis von einer Person prüfen.

## Signale

`signals` listet jede durchgeführte Prüfung auf, damit Sie sehen, worauf die Antwort beruht. Ein `state` von `ai` deutet auf KI-Erzeugung hin.

| `id` | `state` | Prüfung |
| --- | --- | --- |
| `model_1`, `model_2` | `ai`, `unclear`, `clear`, `unavailable` | Zwei unabhängig trainierte Modelle, die die Pixel analysieren. |
| `credentials` | `ai`, `ai_unverified`, `other`, `none` | Content Credentials (C2PA). `ai_unverified`: Die Credentials weisen KI-Erzeugung aus, ihr Aussteller ließ sich aber nicht verifizieren. `other`: Credentials sind vorhanden und enthalten keine Angabe zu KI-Erzeugung. |
| `watermark` | `ai`, `none`, `unavailable` | Unsichtbare Wasserzeichen, die Open-Source-Generierungstools in die Pixel einbetten. |
| `label` | `ai`, `none` | Eine Angabe zur KI-Erzeugung in den Metadaten, etwa der IPTC-Digitalquellentyp. |
| `tool_data` | `ai`, `none` | In der Datei gespeicherte Prompts, Parameter oder Generatornamen. |
| `camera` | `present`, `none` | Kamerahersteller, Modell und Belichtungsdaten. Sie lassen sich ändern und werden von diesem Endpunkt nicht verifiziert. |

`regions` zeigt, wo die Generierungsmerkmale am stärksten sind. Zellen mit Stufe 3 tragen starke Merkmale. Ist die Einstufung `no_ai_signs` und liegen einzelne Zellen auf Stufe 3, kann ein Teil des Bildes mit KI erzeugt oder bearbeitet worden sein: Dieser Endpunkt untersucht keine lokalen Bearbeitungen, führen Sie dafür einen Bildforensik-Bericht aus.

> **Hinweis.** `candidates` ist ein Hinweis, keine Identifizierung. Das Feld ordnet Generatorfamilien danach, wie ähnlich ihnen die Pixelmerkmale sind, und ein Generator außerhalb der Referenzmenge erscheint als nächster Treffer. Verlassen Sie sich auf `generator`, wenn die Datei das Tool selbst nennt.

## Abrechnung

- Die KI-Erkennung für Bilder kostet 4 Credits pro Bild.
- Ein Bildforensik-Bericht für dasselbe Bild im selben Workspace innerhalb von 7 Tagen kostet 36 statt 40 Credits: Die Credits der Erkennung werden einmal angerechnet. Die Analyse weist die Belastung in `usage.credits` aus.
- Anfragen, die vor der Auswertung abgelehnt werden, werden nicht berechnet: ungültige Parameter, nicht unterstützte oder beschädigte Dateien, Größenlimits und Ähnliches. Eine Prüfung, die im Dienst fehlschlägt (`service_unavailable`, `analysis_failed`), wird freigegeben und nicht berechnet.
- Reichen die Credits nicht aus, wird `insufficient_balance` (402) zurückgegeben.

## Was gespeichert wird

Das Bild wird geprüft und gelöscht. Fileverity speichert das Ergebnis ohne das Bild (Einstufung, Antwort, Generator, Signale, Bereiche, Kandidaten, Qualität, Abmessungen, den SHA-256-Fingerabdruck der Datei und die Nutzung) 7 Tage lang, damit die Konsole es anzeigen und die Nutzung abgerechnet und geprüft werden kann. Eine wiederholte Anfrage mit demselben `Idempotency-Key` erhält 24 Stunden lang das gespeicherte Ergebnis. Bilderkennungen sind synchron: Sie erscheinen nicht in `GET /analyses` und senden keine Webhook-Ereignisse. Testschlüssel speichern nichts. Siehe [Datenaufbewahrung und Sicherheit](https://fileverity.com/de/docs/security.md).

## Fehler

| Code | Status | Ursache |
| --- | --- | --- |
| `missing_parameter` | 400 | Das Feld `file` fehlt. |
| `invalid_parameter` | 400 | Ein Feld hat den falschen Typ, es wurde ein unbekanntes Feld gesendet, das Modell ist kein Modell für Bilderkennung, oder der `Idempotency-Key` ist ungültig. |
| `file_not_found` | 400 | Die Datei-ID ist unbekannt, abgelaufen oder bereits verwendet. |
| `unsupported_file`, `invalid_file` | 415, 422 | Die Datei ist kein JPEG-, PNG- oder WebP-Bild oder ist beschädigt. |
| `file_too_large`, `too_many_pixels` | 413 | Die Multipart-Datei überschreitet 4 MB, die hochgeladene Datei überschreitet 10 MB oder das Bild überschreitet 40 Megapixel. |
| `unsupported_media_type`, `invalid_json` | 415, 400 | Der Anfragetext ist weder `multipart/form-data` noch ein JSON-Objekt. |
| `model_not_found` | 404 | Das `model` ist unbekannt. |
| `insufficient_balance`, `spend_limit_reached` | 402 | Das Guthaben oder das monatliche Limit des Schlüssels reicht für die Anfrage nicht aus. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | Der `Idempotency-Key` wurde mit einem anderen Anfragetext verwendet, oder seine erste Anfrage läuft noch. |
| `service_unavailable`, `analysis_failed` | 503, 502 | Der Dienst für die Textprüfung ist vorübergehend nicht verfügbar oder ausgelastet. Es wird nichts berechnet; versuchen Sie es erneut. Bei `service_unavailable` enthält die Antwort den Header `retry-after`. |

> **Hinweis.** Senden Sie einen `Idempotency-Key`, damit ein erneuter Versuch nach einem Timeout nicht doppelt berechnet wird. Siehe [Idempotenz](https://fileverity.com/de/docs/idempotency.md).

