# Analysen

> Bild- und Dokumentanalysen erstellen, das Ergebnis mit Prefer: wait abwarten oder per Polling abfragen, abbrechen, den PDF-Bericht herunterladen sowie Berichtsobjekt und Verifizierungsseite lesen.

Quelle: https://fileverity.com/de/docs/analyses

Eine Analyse ist eine einzelne Bild- oder Dokumentprüfung. Sie prüft eine hochgeladene Datei mit `fvimg-2` (Bilder) oder `fvdoc-3` (Dokumente). Laden Sie die Datei zuerst hoch (siehe [Dateien](https://fileverity.com/de/docs/files.md)) und erstellen Sie dann die Analyse.

Eine Produktübersicht mit Anfrage und Antwort finden Sie unter [KI-generierte Bilder per API erkennen](https://fileverity.com/de/api/ki-bilder-erkennen) und [Dokumentenfälschung per API erkennen](https://fileverity.com/de/api/dokumentenfaelschung-erkennen).

## Analyse erstellen

`POST /analyses` liefert das Analyseobjekt. Der Preis wird beim Erstellen der Analyse reserviert und freigegeben, wenn sie fehlschlägt oder abgebrochen wird.

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `model` | string | Ja | `fvimg-2` oder `fvdoc-3` oder eine Snapshot-ID wie `fvimg-2-2026-10-30`. |
| `file` | string | Ja | ID einer hochgeladenen Datei. |
| `metadata` | object | Nein | Bis zu 16 String-Paare. Schlüssel bis zu 40 Zeichen, Werte bis zu 500. Wird mit der Analyse und in Webhooks zurückgegeben. |
| `options.password` | string | Nein | Passwort eines verschlüsselten Dokuments, bis zu 256 Zeichen. |
| `options.locale` | string | Nein | Sprache der Dokumentbefunde: `en`, `fr`, `de`, `es`, `zh`, `vi` oder `ar`. Standardwert `en`. |

**Analyse erstellen: cURL**

```bash
curl https://api.fileverity.com/v1/analyses \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e5f6a64-52c2-4b36-9d0d-6f3d2f4c9a10" \
  -d '{"model": "fvdoc-3", "file": "file_Pw3mY6zB8Hk2pQ4vN9sL1xR7", "metadata": {"order_id": "A-10492"}}'
```

**Analyse erstellen: JavaScript**

```javascript
const response = await fetch("https://api.fileverity.com/v1/analyses", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ model: "fvdoc-3", file: file.id, metadata: { order_id: "A-10492" } }),
});
const analysis = await response.json();
```

**Analyse erstellen: Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.fileverity.com/v1/analyses",
    headers={
        "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"model": "fvdoc-3", "file": file["id"], "metadata": {"order_id": "A-10492"}},
)
analysis = response.json()
```

## Warten, Polling oder Webhooks

Das Erstellen liefert `202` mit `status: processing`. Das Ergebnis erhalten Sie auf drei Wegen:

- **Warten.** Senden Sie `Prefer: wait=N`, wobei N bis zu 60 Sekunden betragen kann. Die Anfrage wird offen gehalten, bis die Analyse abgeschlossen ist oder N Sekunden vergangen sind. Eine abgeschlossene Analyse liefert `200`; andernfalls erhalten Sie trotzdem `202`. Der Antwort-Header `preference-applied: wait=N` bestätigt die Wartezeit.
- **Polling.** Rufen Sie `GET /analyses/{id}` alle paar Sekunden auf, bis `status` nicht mehr `processing` ist.
- **Webhook.** Abonnieren Sie `analysis.completed` und `analysis.failed` und rufen Sie die Analyse ab, sobald das Ereignis eintrifft. Siehe [Webhooks](https://fileverity.com/de/docs/webhooks.md).

**Bis zum Abschluss abfragen: JavaScript**

```javascript
let analysis = created;
while (analysis.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  const response = await fetch("https://api.fileverity.com/v1/analyses/" + analysis.id, {
    headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },
  });
  analysis = await response.json();
}
```

**Bis zum Abschluss abfragen: Python**

```python
import time

analysis = created
while analysis["status"] == "processing":
    time.sleep(3)
    analysis = requests.get("https://api.fileverity.com/v1/analyses/" + analysis["id"], headers=headers).json()
```

**202 Accepted, Dokument**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvdoc-3-2026-11-03",
  "livemode": true,
  "status": "processing",
  "file": {
    "name": "contract.pdf",
    "bytes": 18874368,
    "format": "pdf"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": null,
  "progress": {
    "stage": "queued",
    "done": 0,
    "total": 0,
    "position": 1
  },
  "usage": {
    "amount": 599,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": {
    "order_id": "A-10492"
  },
  "completed_at": null,
  "expires_at": null
}
```

Solange eine Analyse läuft, ist `progress.stage` eines von `queued`, `reading`, `analyzing` oder `reporting`, und `position` ist die Warteschlangenposition, solange die Phase `queued` ist. Dokumente können in die Warteschlange gestellt werden. Das Warten ist bei Dokumenten optional und kann enden, bevor das Ergebnis vorliegt; behandeln Sie `202` daher immer.

## Wenn der Dienst ausgelastet ist

Wenn die Kapazität ausgelastet ist, liefert `POST /analyses` `503` mit dem Code `service_unavailable` und einem Header `retry-after`. Es wird nichts berechnet. Warten Sie die in `retry-after` angegebene Anzahl Sekunden und versuchen Sie es dann mit demselben `Idempotency-Key` erneut, damit der erneute Versuch nie eine Prüfung doppelt ausführen kann. Für den besten Durchsatz führen Sie Bildanalysen nacheinander statt parallel aus.

**Erneut versuchen bei Auslastung: JavaScript**

```javascript
async function create(body, key) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch("https://api.fileverity.com/v1/analyses", {
      method: "POST",
      headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": key },
      body: JSON.stringify(body),
    });
    if (response.status !== 503) return response;
    const wait = Number(response.headers.get("retry-after")) || 15;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error("Service busy");
}
```

**Erneut versuchen bei Auslastung: Python**

```python
import time

def create(body, key):
    for attempt in range(5):
        response = requests.post("https://api.fileverity.com/v1/analyses", headers={**headers, "Idempotency-Key": key}, json=body)
        if response.status_code != 503:
            return response
        time.sleep(int(response.headers.get("retry-after", 15)))
    raise RuntimeError("Service busy")
```

## Statuswerte

| Status | Bedeutung |
| --- | --- |
| `processing` | Die Analyse läuft. `result` ist `null`. |
| `succeeded` | Das Ergebnis liegt vor. `report_id`, `report_url`, `summary` und `result` sind gesetzt. |
| `failed` | Die Analyse konnte nicht abgeschlossen werden. `error` enthält `code` und `message`. Es wurde nichts berechnet. |
| `canceled` | Sie haben sie abgebrochen. `error.code` ist `canceled`. Es wurde nichts berechnet. |

**Fehlgeschlagene Analyse**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "failed",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": {
    "code": "analysis_failed",
    "message": "The analysis could not be completed. You were not charged; retry it, and contact support with the request ID if it fails again."
  },
  "progress": null,
  "usage": {
    "amount": 0,
    "currency": "usd",
    "funding": null
  },
  "metadata": null,
  "completed_at": 1793700135,
  "expires_at": null
}
```

## Das Berichtsobjekt

Eine erfolgreiche Analyse enthält denselben Bericht, den die Website, das PDF und die Verifizierungsseite zeigen.

| Feld | Beschreibung |
| --- | --- |
| `report_id` | Berichts-ID, `FV-XXXX-XXXX-XXXX`. |
| `report_url` | Öffentliche Verifizierungsseite für den Bericht. Wer den Link hat, kann Berichts-ID, Fingerabdruck der Datei und Zeitstempel ohne Konto mit dem hinterlegten Datensatz abgleichen. |
| `summary` | Die kurze Einstufung. Siehe unten. |
| `result.report` | Der vollständige Bericht. `result.report.schema` ist `fileverity.report/1` für Bilder und `fileverity.docpro/1` für Dokumente. |
| `result.stamped_at` | Unix-Zeitstempel des für den Bericht ausgestellten Zeitstempels nach RFC 3161 oder `null`. |
| `usage` | Berechneter Betrag `amount` in Cent (0 bei Prüfungen aus dem kostenlosen Start und bei Fehlern), `currency` und `funding` (`trial` oder `balance`). |
| `metadata` | Die von Ihnen gesendeten Metadaten oder `null`. |
| `expires_at` | Unix-Zeitstempel, nach dem `result` entfernt wird. Ergebnisse werden 7 Tage lang aufbewahrt. |

**200 OK, Bild**

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

Das Objekt `report` ist oben gekürzt; das echte enthält die vollständigen Befunde.

Die `summary` ist die stabile, maschinenlesbare Einstufung. `result.report` ist der vollständige Bericht, den die Website und das PDF darstellen. Seine Struktur folgt dem Schema, das in `result.report.schema` genannt wird. Innerhalb derselben Schemaversion behalten aufgeführte Felder ihren Namen und ihre Bedeutung, und es können neue Felder hinzukommen; ignorieren Sie daher Felder, die Sie nicht kennen.

### Zusammenfassung bei Bildern

| Feld | Werte |
| --- | --- |
| `level` | `L0` Nicht bestimmbar, `L1` Quelle verifiziert, `L2` Keine Auffälligkeiten, `L3` Manuelle Prüfung erforderlich, `L4` Hochgradig verdächtig, `L5` Starke Hinweise gegen die Echtheit. |
| `action` | `accept`, `review`, `reject`, `resubmit` |
| `assessment` | `authentic_untouched`, `authentic_locally_edited`, `ai_generated`, `undetermined` |
| `ai` | `labelled`, `very_likely`, `suspected`, `undecided`, `low`, `very_low`, `not_evaluated` |
| `edit` | `detected`, `suspected`, `suspected_record`, `review`, `generative`, `minor`, `none`, `not_applicable`, `not_evaluated` |

### Zusammenfassung bei Dokumenten

| Feld | Beschreibung |
| --- | --- |
| `kind` | Immer `docpro`. |
| `level` | `L0` Nicht bestimmbar, `L1` Quelle verifiziert, `L2` Keine Anzeichen von Manipulation, `L3` Manuelle Prüfung erforderlich, `L4` Hohes Risiko, `L5` Probleme nachgewiesen. |
| `action` | `accept`, `note` (im Bericht markierte KI-Inhalte anhand Ihrer Richtlinie prüfen), `review`, `reject` oder `resubmit`. |
| `reason` | Der Befund oder Zustand hinter der Stufe, zum Beispiel `clean`, `incomplete` oder eine Befund-ID, oder `null`. |
| `findings` | IDs der relevanten Befunde. |
| `pages`, `images` | Seiten des Dokuments und untersuchte eingebettete Fotos. |
| `text` | Die Einstufung des Dokumenttextes (`ai_generated`, `mixed`, `human`, `inconclusive`) oder `null`, wenn der Text nicht ausgewertet wurde. |
| `strong` | `true`, wenn ein aufgeführter Befund stark ist. Fehlt andernfalls. |

**200 OK, Dokument**

```json
{
  "id": "an_Zc4vB7nP1sK8tL3wR6yQm2Xa",
  "object": "analysis",
  "created": 1793700300,
  "model": "fvdoc-3-2026-11-03",
  "livemode": true,
  "status": "succeeded",
  "file": {
    "name": "contract.pdf",
    "bytes": 18874368,
    "format": "pdf"
  },
  "report_id": "FV-3PXH-6WQ2-8NDC",
  "report_url": "https://fileverity.com/verify/FV-3PXH-6WQ2-8NDC",
  "summary": {
    "kind": "docpro",
    "level": "L3",
    "action": "review",
    "reason": null,
    "findings": [],
    "pages": 12,
    "images": 3,
    "text": "human"
  },
  "result": {
    "report": {
      "schema": "fileverity.docpro/1",
      "id": "FV-3PXH-6WQ2-8NDC"
    },
    "stamped_at": 1793700340
  },
  "error": null,
  "progress": null,
  "usage": {
    "amount": 599,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": null,
  "completed_at": 1793700341,
  "expires_at": 1794305141
}
```

### Felder des Bildberichts

`result.report` einer Bildanalyse. Verschachtelte Objekte sind in der [API-Referenz](https://fileverity.com/de/docs/api-reference.md#create-analysis) aufgeführt.

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `schema` | `"fileverity.report/1"` | Ja |  |
| `id` | string | Ja | Berichts-ID, FV-XXXX-XXXX-XXXX. |
| `sample` | `true` | Nein | Vorhanden in den festen Beispielberichten, die Testschlüssel liefern. |
| `issuedAt` | string | Nein | Zeitpunkt der Ausstellung des Berichts, ISO 8601 in UTC. Format date-time. |
| `issuer` | object | Nein | Aussteller des Berichts. |
| `file` | object | Nein | Das geprüfte Bild. |
| `pro` | object | Nein | Die Einstufung. Dieselben Werte wie summary, mit reason. |
| `score` | integer oder null | Nein | Echtheitswert von 0 bis 100 in Schritten von 5: wie stark die Belege dafür sprechen, dass das Bild eine echte, unbearbeitete Aufnahme ist. null, wenn nicht ausgewertet. |
| `confidence` | einer der Werte `"high"`, `"medium"`, `"low"` | Nein | Wie viel sich anhand dieser Datei feststellen lässt. Eine geringe Aussagesicherheit liegt meist an der Datei selbst, etwa an niedriger Auflösung oder starker Komprimierung. |
| `questions` | object | Nein | Die drei Fragen, die der Bericht beantwortet. |
| `generator` | object oder null | Nein | Der für das Bild genannte KI-Generator oder null. |
| `regions` | array von object | Nein | Markierte Bereiche, in Pixeln des angezeigten Bildes. |
| `provenance` | object | Nein | Was die eigenen Angaben der Datei über ihre Herkunft aussagen. |
| `digest` | string | Nein | Fingerabdruck des Berichtsinhalts, den die Verifizierungsseite verwendet. |

### Felder des Dokumentberichts

`result.report` einer Dokumentanalyse.

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `schema` | `"fileverity.docpro/1"` | Ja |  |
| `id` | string | Ja | Berichts-ID, FV-XXXX-XXXX-XXXX. |
| `sample` | `true` | Nein | Vorhanden in den festen Beispielberichten, die Testschlüssel liefern. |
| `issuedAt` | string | Nein | Zeitpunkt der Ausstellung des Berichts, ISO 8601 in UTC. Format date-time. |
| `receivedAt` | string | Nein | Zeitpunkt des Dateieingangs, ISO 8601 in UTC. Format date-time. |
| `issuer` | object | Nein | Aussteller des Berichts. |
| `file` | object | Nein | Das geprüfte Dokument. |
| `level` | einer der Werte `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | Nein | Risikostufe, L0 bis L5. |
| `action` | einer der Werte `"accept"`, `"note"`, `"review"`, `"reject"`, `"resubmit"` | Nein |  |
| `reason` | string oder null | Nein | Der Befund oder Zustand hinter der Stufe. |
| `findings` | array von object | Nein | Die Befunde hinter der Stufe, jeweils mit den Seiten und eingebetteten Fotos, auf die sie sich beziehen. |
| `text` | object | Nein | Das Ergebnis für den Text des Dokuments. |
| `images` | array von object | Nein | Die eingebetteten Fotos und Grafiken, in Dokumentreihenfolge nummeriert. |
| `structure` | object oder null | Nein | Der Änderungsverlauf der Datei oder null, wenn er nicht untersucht wurde. |
| `provenance` | object | Nein | Was die eigenen Angaben der Datei über ihre Herkunft aussagen. |
| `digest` | string | Nein | Fingerabdruck des Berichtsinhalts, den die Verifizierungsseite verwendet. |

## Abrufen, auflisten und abbrechen

- `GET /analyses/{id}` liefert die Analyse, einschließlich ihres Ergebnisses, solange dieses aufbewahrt wird.
- `GET /analyses` listet die Analysen des Workspace auf, die neuesten zuerst. `limit` liegt zwischen 1 und 100 (Standardwert 20), `type` filtert nach `image` oder `document`, und `starting_after` nimmt den `next_cursor` der vorherigen Seite entgegen. Listeneinträge enthalten nie `result`.
- `POST /analyses/{id}/cancel` bricht eine noch laufende Dokumentanalyse ab und gibt den reservierten Betrag frei. Bildanalysen lassen sich nicht abbrechen; ein verspätetes oder bereits abgeschlossenes Abbrechen liefert `not_cancelable`.

**Auflisten und abbrechen: cURL**

```bash
curl "https://api.fileverity.com/v1/analyses?limit=20&type=document" \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"

curl -X POST https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/cancel \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

## PDF-Bericht

`GET /analyses/{id}/report.pdf` lädt den versiegelten PDF-Bericht einer erfolgreichen Analyse herunter, solange deren Ergebnis aufbewahrt wird. Ergänzen Sie `?locale=` mit `en`, `fr`, `de`, `es`, `zh`, `vi` oder `ar` (Standardwert `en`). Senden Sie den Header `Authorization`; die Antwort ist `application/pdf`.

**PDF herunterladen: cURL**

```bash
curl "https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/report.pdf?locale=en" \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -o Fileverity-FV-7K2M-9QXD-4T8R.pdf
```

Bei Dokumenten werden Seitenbilder und Textauszüge nach der Prüfung 3 Stunden lang aufbewahrt. Danach enthält das PDF sie nicht mehr, und der Antwort-Header `x-evidence-included` ist `false`. Wenn das PDF die Belege enthalten soll, laden Sie es herunter, sobald die Analyse abgeschlossen ist.

## Fehler

| Code | Status | Ursache |
| --- | --- | --- |
| `file_not_found` | 400 | Die Datei-ID ist unbekannt, abgelaufen oder bereits verwendet, oder der Upload an `upload.url` ist noch nicht abgeschlossen. |
| `model_not_found` | 404 | Unbekanntes Modell. |
| `invalid_parameter` | 400 | Ein Feld fehlt, hat einen falschen Typ oder ist unbekannt. Textmodelle verwenden Sie mit `POST /text/detections`. |
| `unsupported_file`, `invalid_file` | 415, 422 | Das Dateiformat wird für das Modell nicht unterstützt, oder die Datei ist beschädigt. |
| `file_too_large`, `too_many_pixels`, `too_many_pages`, `document_too_long` | 413 | Ein Größenlimit wurde überschritten. |
| `password_required`, `wrong_password` | 422 | Das Dokument ist verschlüsselt. Senden Sie `options.password`. |
| `not_examinable` | 422 | Im Dokument lässt sich nichts untersuchen. Es wird nichts berechnet. |
| `insufficient_balance`, `spend_limit_reached` | 402 | Das Guthaben oder das monatliche Ausgabenlimit des Schlüssels reicht für den Preis nicht aus. |
| `service_unavailable`, `analysis_failed` | 503, 502 | Ein vorübergehender Fehler oder ausgelastete Kapazität. Es wird nichts berechnet; wiederholen Sie die Anfrage. Bei `service_unavailable` enthält die Antwort den Header `retry-after`. Siehe [Wenn der Dienst ausgelastet ist](https://fileverity.com/de/docs/analyses.md#busy). |
| `unsupported_media_type` | 415 | Der Anfragetext wird nicht als `application/json` gesendet. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | Der `Idempotency-Key` wurde mit einem anderen Anfragetext verwendet, oder seine erste Anfrage läuft noch. Siehe [Idempotenz](https://fileverity.com/de/docs/idempotency.md). |
| `not_cancelable` | 409 | Nur Dokumente, die noch verarbeitet werden, lassen sich abbrechen. |

> **Hinweis.** Manche Fehler treten erst auf, nachdem die Analyse erstellt wurde, zum Beispiel wenn ein Modell die Verarbeitung nicht abschließen kann. Sie setzen an der Analyse `status: failed` und `error`; der Aufruf zum Erstellen schlägt nicht fehl, und der Webhook `analysis.failed` wird ausgelöst. Siehe [Fehler](https://fileverity.com/de/docs/errors.md).