Fileverity-API-Dokumentation

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.

Als Markdown ansehenAktualisiert am 2026-11-04

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) und erstellen Sie dann die Analyse.

Eine Produktübersicht mit Anfrage und Antwort finden Sie unter KI-generierte Bilder per API erkennen und Dokumentenfälschung per API 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`.

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"}}'

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();

import osimport uuidimport 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.

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();}

import time analysis = createdwhile analysis["status"] == "processing":    time.sleep(3)    analysis = requests.get("https://api.fileverity.com/v1/analyses/" + analysis["id"], headers=headers).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.

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");}

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.

{  "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.

{  "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.

{  "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 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.

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.

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.
`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.
`not_cancelable`	409	Nur Dokumente, die noch verarbeitet werden, lassen sich abbrechen.

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.