# API-Referenz

> Jeder Endpunkt der Fileverity-API mit Parametern, Anfrage- und Antwortschemas, Fehlercodes und Beispielen, erzeugt aus der OpenAPI-3.1-Spezifikation.

Quelle: https://fileverity.com/de/docs/api-reference

Diese Referenz wird aus dem OpenAPI-3.1-Dokument der API erzeugt, das unter [https://api.fileverity.com/v1/openapi.json](https://api.fileverity.com/v1/openapi.json) verfügbar ist, und stimmt daher immer mit der API überein. Für Konzepte und Anleitungen beginnen Sie mit der [Übersicht](https://fileverity.com/de/docs.md).

## Konventionen

Basis-URL: `https://api.fileverity.com/v1`. Authentifizieren Sie jede Anfrage mit `Authorization: Bearer <key>`. Fehler haben ein einheitliches Format, das unter [Fehler](https://fileverity.com/de/docs/errors.md) beschrieben ist. Jede Antwort enthält einen Header `x-request-id`, und authentifizierte Antworten enthalten die unter [Rate-Limits und Header](https://fileverity.com/de/docs/rate-limits.md) beschriebenen Rate-Limit-Header. Verschachtelte Objekte lassen sich in ausklappbaren Bereichen unter der Tabelle öffnen.

## Textprüfungen

### Von KI verfassten Text erkennen

`POST` `https://api.fileverity.com/v1/text/detections`

Stuft reinen Text als von KI verfasst, teilweise von KI verfasst oder von Menschen verfasst ein und gibt die von KI verfassten Passagen zurück. Der Text wird ausgewertet und verworfen; er wird nicht gespeichert. Abgerechnet werden Unicode-Codepoints in Einheiten von 1.000 Zeichen, pro Anfrage aufgerundet. Anfragen, die vor der Auswertung abgelehnt werden, werden nicht berechnet. Testschlüssel liefern kostenlos ein festes Ergebnis für einen von Menschen verfassten Text.

#### Parameter

| Name | Ort | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | Header | string | Nein | Eindeutiger Schlüssel mit bis zu 255 Zeichen. Wird die Anfrage innerhalb von 24 Stunden mit demselben Schlüssel und demselben Anfragetext wiederholt, gibt sie die erste Antwort mit dem Header idempotent-replayed: true zurück; derselbe Schlüssel mit einem anderen Anfragetext gibt 409 zurück. |

#### Anfragetext: application/json, erforderlich

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `model` | string | Nein | Modell-ID oder Snapshot-ID. Standardwert `"fvdoc-3-text"`. |
| `text` | string | Ja | Reiner Text mit mindestens 100 Wörtern und höchstens 100.000 Zeichen. |
| `language` | einer der Werte `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `null` | Nein | ISO-639-1-Code. Wird automatisch erkannt, wenn er weggelassen wird. Standardwert `null`. |

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 200 | Das Erkennungsergebnis. | `TextDetection` |
| 400 | Ungültige Anfrage. Fehlercodes: invalid_json, missing_parameter, text_too_short, unsupported_language, invalid_parameter. | `Error` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 402 | Das Guthaben oder das monatliche Ausgabenlimit des Schlüssels reicht für die Anfrage nicht aus. Fehlercodes: insufficient_balance, spend_limit_reached. | `Error` |
| 404 | Ressource nicht gefunden. Fehlercodes: model_not_found. | `Error` |
| 409 | Konflikt mit dem aktuellen Zustand. Fehlercodes: idempotency_mismatch, idempotency_in_progress. | `Error` |
| 413 | Ein Größenlimit wurde überschritten. Fehlercodes: text_too_long. | `Error` |
| 415 | Nicht unterstützter Medientyp oder nicht unterstütztes Dateiformat. Fehlercodes: unsupported_media_type. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |
| 502 | Die Analyse konnte nicht abgeschlossen werden; nicht berechnet. Fehlercodes: analysis_failed. | `Error` |
| 503 | Vorübergehend nicht verfügbar oder ausgelastet; nicht berechnet. Versuchen Sie es nach der im Header retry-after angegebenen Anzahl von Sekunden erneut. Fehlercodes: service_unavailable. | `Error` |

#### Antwort 200: TextDetection

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja |  |
| `object` | `"text.detection"` | Ja |  |
| `created` | integer | Ja | Unix-Zeitstempel. |
| `model` | string | Ja | Snapshot, der das Ergebnis erzeugt hat. |
| `livemode` | boolean | Ja | Bei Testschlüsseln false. |
| `language` | einer der Werte `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"` | Ja |  |
| `verdict` | einer der Werte `"ai"`, `"mixed"`, `"human"` | Ja | ai: Der Text wirkt durchgehend von KI verfasst; mixed: von KI verfasste Passagen in einem von Menschen verfassten Text; human: keine von KI verfasste Passage gefunden. |
| `score` | number | Ja | Modell-Score für die Passage mit der stärksten KI-Ähnlichkeit. Minimum 0. Maximum 1. |
| `ai_fraction` | number | Ja | Anteil des ausgewerteten Textes, der in von KI verfassten Segmenten liegt. Minimum 0. Maximum 1. |
| `segments` | array von object | Ja | Von KI verfasste Passagen als Offsets im gesendeten Text, in Unicode-Codepoints. Die Grenzen sind ungefähr und können angrenzende Sätze einschließen. |
| `usage` | object | Ja |  |

**segments: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `start` | integer | Ja |  |
| `end` | integer | Ja | Exklusiv. |
| `score` | number | Ja | Minimum 0. Maximum 1. |

**usage: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `characters` | integer | Ja | Ausgewertete Unicode-Codepoints. |
| `free_characters` | integer | Ja | Zeichen, die durch Ihr Kontingent des kostenlosen Starts abgedeckt sind und nicht berechnet werden. |
| `billed_units` | integer | Ja | Tatsächlich berechnete Einheiten zu 1.000 Zeichen, nach Abzug der kostenlosen Zeichen; billed_units × Preis pro Einheit ergibt die Kosten. |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `invalid_json` | 400 |
| `missing_parameter` | 400 |
| `unsupported_media_type` | 415 |
| `text_too_short` | 400 |
| `text_too_long` | 413 |
| `unsupported_language` | 400 |
| `model_not_found` | 404 |
| `insufficient_balance` | 402 |
| `spend_limit_reached` | 402 |
| `service_unavailable` | 503 |
| `analysis_failed` | 502 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

**Anfrage: cURL**

```bash
curl https://api.fileverity.com/v1/text/detections \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -Rs '{text: .}' essay.txt)"
```

**Antwort**

```json
{
  "id": "tdet_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "text.detection",
  "created": 1793664000,
  "model": "fvdoc-3-text-2026-11-03",
  "livemode": true,
  "language": "en",
  "verdict": "mixed",
  "score": 0.97,
  "ai_fraction": 0.41,
  "segments": [
    {
      "start": 212,
      "end": 433,
      "score": 0.97
    },
    {
      "start": 579,
      "end": 790,
      "score": 0.93
    }
  ],
  "usage": {
    "characters": 1412,
    "free_characters": 0,
    "billed_units": 2
  }
}
```

## Dateien

### Datei hochladen

`POST` `https://api.fileverity.com/v1/files`

Lädt eine Datei zur Analyse hoch. Senden Sie Dateien bis 4 MB als multipart/form-data im Feld file; die Antwort hat den Status uploaded. Dateien über 4 MB müssen über eine vorsignierte URL hochgeladen werden. Senden Sie JSON mit filename, content_type und bytes (Dokumente bis 50 MB); die Antwort hat den Status pending und ein Objekt upload mit einer vorsignierten URL: Senden Sie die Dateibytes vor deren Ablauf mit PUT und den angegebenen Headern an diese URL. Eine Datei wird gelöscht, wenn eine Analyse startet, spätestens aber nach 24 Stunden. Ein Workspace kann pro Modus gleichzeitig bis zu 50 nicht abgelaufene Dateien und 200 MB enthalten.

#### Parameter

| Name | Ort | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | Header | string | Nein | Eindeutiger Schlüssel mit bis zu 255 Zeichen. Wird die Anfrage innerhalb von 24 Stunden mit demselben Schlüssel und demselben Anfragetext wiederholt, gibt sie die erste Antwort mit dem Header idempotent-replayed: true zurück; derselbe Schlüssel mit einem anderen Anfragetext gibt 409 zurück. |

#### Anfragetext: multipart/form-data, erforderlich

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `file` | string | Ja | Format binary. |

#### Anfragetext: application/json, erforderlich

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `filename` | string | Nein |  |
| `content_type` | string | Ja | MIME-Typ der Datei, zum Beispiel image/jpeg oder application/pdf. |
| `bytes` | integer | Ja | Genaue Größe in Bytes. Minimum 1. Maximum 52.428.800. |

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 201 | Die Datei. | `File` |
| 400 | Ungültige Anfrage. Fehlercodes: invalid_json, missing_parameter, invalid_parameter. | `Error` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 409 | Konflikt mit dem aktuellen Zustand. Fehlercodes: idempotency_mismatch, idempotency_in_progress. | `Error` |
| 413 | Ein Größenlimit wurde überschritten. Fehlercodes: file_too_large. | `Error` |
| 415 | Nicht unterstützter Medientyp oder nicht unterstütztes Dateiformat. Fehlercodes: unsupported_media_type, unsupported_file. | `Error` |
| 422 | Die Datei kann nicht verarbeitet werden. Fehlercodes: invalid_file. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: pending_files_limit, rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |

#### Antwort 201: File

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja |  |
| `object` | `"file"` | Ja |  |
| `filename` | string oder null | Ja |  |
| `bytes` | integer oder null | Ja |  |
| `content_type` | string | Ja |  |
| `status` | einer der Werte `"pending"`, `"uploaded"` | Ja | pending, bis die an die vorsignierte URL gesendeten Bytes angekommen sind. |
| `livemode` | boolean | Ja | Dateien sind nur für Schlüssel desselben Modus sichtbar. |
| `created` | integer | Ja | Unix-Zeitstempel. |
| `expires_at` | integer | Ja | Unix-Zeitstempel, nach dem die Datei gelöscht wird. |
| `upload` | object | Nein | In der Antwort auf eine JSON-Upload-Anfrage vorhanden. |

**upload: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `url` | string | Ja | Testschlüssel erhalten eine Platzhalter-URL (test: true); es wird nichts hochgeladen oder gespeichert. |
| `method` | `"PUT"` | Ja |  |
| `headers` | object mit string-Werten | Ja |  |
| `expires_at` | integer | Ja | Unix-Zeitstempel. |
| `test` | `true` | Nein |  |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `invalid_json` | 400 |
| `missing_parameter` | 400 |
| `unsupported_media_type` | 415 |
| `unsupported_file` | 415 |
| `invalid_file` | 422 |
| `file_too_large` | 413 |
| `pending_files_limit` | 429 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

**Anfrage: cURL**

```bash
curl https://api.fileverity.com/v1/files \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -F file=@claim-photo.jpg
```

**Antwort**

```json
{
  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "file",
  "filename": "claim-photo.jpg",
  "bytes": 2481920,
  "content_type": "image/jpeg",
  "status": "uploaded",
  "livemode": true,
  "created": 1793700000,
  "expires_at": 1793786400
}
```

### Datei abrufen

`GET` `https://api.fileverity.com/v1/files/{id}`

Gibt die Datei zurück und zeigt, ob ihre Bytes angekommen sind.

#### Parameter

| Name | Ort | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- | --- |
| `id` | Pfad | string | Ja | Datei-ID. |

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 200 | Die Datei. | `File` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 404 | Ressource nicht gefunden. Fehlercodes: not_found. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |

#### Antwort 200: File

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja |  |
| `object` | `"file"` | Ja |  |
| `filename` | string oder null | Ja |  |
| `bytes` | integer oder null | Ja |  |
| `content_type` | string | Ja |  |
| `status` | einer der Werte `"pending"`, `"uploaded"` | Ja | pending, bis die an die vorsignierte URL gesendeten Bytes angekommen sind. |
| `livemode` | boolean | Ja | Dateien sind nur für Schlüssel desselben Modus sichtbar. |
| `created` | integer | Ja | Unix-Zeitstempel. |
| `expires_at` | integer | Ja | Unix-Zeitstempel, nach dem die Datei gelöscht wird. |
| `upload` | object | Nein | In der Antwort auf eine JSON-Upload-Anfrage vorhanden. |

**upload: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `url` | string | Ja | Testschlüssel erhalten eine Platzhalter-URL (test: true); es wird nichts hochgeladen oder gespeichert. |
| `method` | `"PUT"` | Ja |  |
| `headers` | object mit string-Werten | Ja |  |
| `expires_at` | integer | Ja | Unix-Zeitstempel. |
| `test` | `true` | Nein |  |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

**Anfrage: cURL**

```bash
curl https://api.fileverity.com/v1/files/file_8Hk2pQ4vN9sL1xR7cW3mY6zB \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Antwort**

```json
{
  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "file",
  "filename": "claim-photo.jpg",
  "bytes": 2481920,
  "content_type": "image/jpeg",
  "status": "uploaded",
  "livemode": true,
  "created": 1793700000,
  "expires_at": 1793786400
}
```

### Datei löschen

`DELETE` `https://api.fileverity.com/v1/files/{id}`

Löscht eine hochgeladene Datei und ihre gespeicherten Bytes.

#### Parameter

| Name | Ort | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- | --- |
| `id` | Pfad | string | Ja | Datei-ID. |

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 200 | Die Datei wurde gelöscht. | `FileDeleted` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 404 | Ressource nicht gefunden. Fehlercodes: not_found. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |

#### Antwort 200: FileDeleted

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja |  |
| `object` | `"file"` | Ja |  |
| `deleted` | `true` | Ja |  |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

**Anfrage: cURL**

```bash
curl -X DELETE https://api.fileverity.com/v1/files/file_8Hk2pQ4vN9sL1xR7cW3mY6zB \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Antwort**

```json
{
  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "file",
  "deleted": true
}
```

## Analysen

### Analyse erstellen

`POST` `https://api.fileverity.com/v1/analyses`

Analysiert eine hochgeladene Datei mit fvimg-2 (Bilder) oder fvdoc-3 (Dokumente). Eine Analyse ist eine einzelne Bild- oder Dokumentprüfung. Die Antwort ist 202 mit dem Status processing; das Ergebnis trifft per Webhook ein oder lässt sich per Polling über GET /analyses/{id} abrufen. Senden Sie Prefer: wait=N (bis zu 60 Sekunden), um die Anfrage offen zu halten, bis das Ergebnis vorliegt; eine abgeschlossene Analyse gibt 200 zurück. Der Preis wird beim Erstellen der Analyse reserviert und freigegeben, wenn sie fehlschlägt oder abgebrochen wird. Ergebnisse werden 7 Tage aufbewahrt. Ist die Kapazität ausgelastet, gibt die API 503 service_unavailable mit einem Header retry-after zurück und berechnet nichts: Wiederholen Sie die Anfrage mit demselben Idempotency-Key und führen Sie Bildanalysen nacheinander aus, um den besten Durchsatz zu erzielen. Testschlüssel liefern ein Beispielergebnis und werden nie berechnet; der Beispielbericht enthält nur wenige Felder.

#### Parameter

| Name | Ort | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | Header | string | Nein | Eindeutiger Schlüssel mit bis zu 255 Zeichen. Wird die Anfrage innerhalb von 24 Stunden mit demselben Schlüssel und demselben Anfragetext wiederholt, gibt sie die erste Antwort mit dem Header idempotent-replayed: true zurück; derselbe Schlüssel mit einem anderen Anfragetext gibt 409 zurück. |
| `Prefer` | Header | string | Nein | wait=N hält die Anfrage bis zu N Sekunden (maximal 60) offen, bis die Analyse abgeschlossen ist. |

#### Anfragetext: application/json, erforderlich

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `model` | einer der Werte `"fvimg-2"`, `"fvimg-2-2026-10-30"`, `"fvdoc-3"`, `"fvdoc-3-2026-11-03"` | Ja | Modell-ID oder Snapshot-ID. fvimg-2 analysiert Bilder, fvdoc-3 Dokumente. |
| `file` | string | Ja | ID einer hochgeladenen Datei. |
| `metadata` | object mit string-Werten | Nein | Bis zu 16 String-Paare (Schlüssel bis zu 40 Zeichen, Werte bis zu 500), die mit der Analyse und in Webhooks zurückgegeben werden. |
| `options` | object | Nein |  |

**options: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `password` | string | Nein | Passwort eines verschlüsselten Dokuments. Maximale Länge 256. |
| `locale` | einer der Werte `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `"vi"`, `"ar"` | Nein | Sprache der Dokumentbefunde. Standardwert `"en"`. |

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 200 | Die abgeschlossene Analyse. | `Analysis` |
| 202 | Die Analyse wird verarbeitet. | `Analysis` |
| 400 | Ungültige Anfrage. Fehlercodes: invalid_json, missing_parameter, file_not_found, invalid_parameter. | `Error` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 402 | Das Guthaben oder das monatliche Ausgabenlimit des Schlüssels reicht für die Anfrage nicht aus. Fehlercodes: insufficient_balance, spend_limit_reached. | `Error` |
| 404 | Ressource nicht gefunden. Fehlercodes: model_not_found. | `Error` |
| 409 | Konflikt mit dem aktuellen Zustand. Fehlercodes: idempotency_mismatch, idempotency_in_progress. | `Error` |
| 413 | Ein Größenlimit wurde überschritten. Fehlercodes: file_too_large, too_many_pixels, too_many_pages, document_too_long. | `Error` |
| 415 | Nicht unterstützter Medientyp oder nicht unterstütztes Dateiformat. Fehlercodes: unsupported_media_type, unsupported_file. | `Error` |
| 422 | Die Datei kann nicht verarbeitet werden. Fehlercodes: invalid_file, password_required, wrong_password, not_examinable. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |
| 502 | Die Analyse konnte nicht abgeschlossen werden; nicht berechnet. Fehlercodes: analysis_failed. | `Error` |
| 503 | Vorübergehend nicht verfügbar oder ausgelastet; nicht berechnet. Versuchen Sie es nach der im Header retry-after angegebenen Anzahl von Sekunden erneut. Fehlercodes: service_unavailable. | `Error` |

#### Antwort 200: Analysis

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja |  |
| `object` | `"analysis"` | Ja |  |
| `created` | integer | Ja | Unix-Zeitstempel. |
| `model` | string | Ja | Snapshot, der das Ergebnis erzeugt hat. |
| `livemode` | boolean | Ja |  |
| `status` | einer der Werte `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Ja |  |
| `file` | object | Ja |  |
| `report_id` | string oder null | Ja | Überprüfbare Berichts-ID, FV-XXXX-XXXX-XXXX. |
| `report_url` | string oder null | Ja | Öffentliche Verifizierungsseite des Berichts. |
| `summary` | `ImageSummary` oder `DocumentSummary` oder null | Ja | Die kurze, stabile Einstufung: eine ImageSummary für Bilder, eine DocumentSummary für Dokumente, null, bis die Analyse erfolgreich abgeschlossen ist. |
| `result` | object oder null | Ja | Vorhanden, sobald der Status succeeded ist, und bis das Ergebnis abläuft. |
| `error` | object oder null | Ja |  |
| `progress` | object oder null | Ja |  |
| `usage` | object | Ja |  |
| `metadata` | object oder null | Ja |  |
| `completed_at` | integer oder null | Ja |  |
| `expires_at` | integer oder null | Ja | Unix-Zeitstempel, nach dem das Ergebnis gelöscht wird. |

**file: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `name` | string oder null | Nein |  |
| `bytes` | integer oder null | Nein |  |
| `format` | string oder null | Nein |  |

**summary (ImageSummary): Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `level` | einer der Werte `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | Ja | Risikostufe, L0 bis L5. |
| `assessment` | einer der Werte `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"` | Ja |  |
| `action` | einer der Werte `"accept"`, `"review"`, `"reject"`, `"resubmit"` | Ja |  |
| `ai` | einer der Werte `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"` | Ja | Der Befund zur KI-Erzeugung. |
| `edit` | einer der Werte `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"` | Ja | Der Befund zur lokalen Bearbeitung. |

**summary (DocumentSummary): Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `kind` | `"docpro"` | Ja |  |
| `level` | einer der Werte `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | Ja | Risikostufe, L0 bis L5. |
| `action` | einer der Werte `"accept"`, `"note"`, `"review"`, `"reject"`, `"resubmit"` | Ja | note: Prüfen Sie die im Bericht markierten KI-Inhalte anhand Ihrer Richtlinie. |
| `reason` | string oder null | Ja | Der Befund oder Zustand hinter der Stufe, zum Beispiel clean oder incomplete, oder eine Befund-ID. |
| `findings` | array von string | Ja | IDs der relevanten Befunde. |
| `pages` | integer | Ja | Seiten im Dokument. |
| `images` | integer | Ja | Untersuchte eingebettete Fotos. |
| `text` | einer der Werte `"ai_generated"`, `"mixed"`, `"human"`, `"inconclusive"`, `null` | Ja | Die Einstufung des Dokumenttexts oder null, wenn der Text nicht ausgewertet wurde. |
| `strong` | `true` | Nein | Vorhanden, wenn ein aufgeführter Befund stark ist. |

**result: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `report` | `ImageReport` oder `DocumentReport` | Nein | Der vollständige Bericht. report.schema ist fileverity.report/1 für Bilder und fileverity.docpro/1 für Dokumente. |
| `stamped_at` | integer oder null | Nein | Unix-Zeitstempel des für den Bericht ausgestellten RFC-3161-Zeitstempels oder null. |

**report (ImageReport): Felder**

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

**issuer: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `name` | string | Nein |  |
| `operator` | string | Nein |  |
| `verify` | string | Nein | Öffentliche Verifizierungsseite des Berichts. |

**file: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `name` | string oder null | Nein |  |
| `sha256` | string | Nein | SHA-256-Hash der geprüften Datei, hexadezimal. |
| `bytes` | integer | Nein |  |
| `width` | integer | Nein | Breite in Pixeln, wie angezeigt. |
| `height` | integer | Nein | Höhe in Pixeln, wie angezeigt. |
| `format` | string | Nein |  |

**pro: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `level` | einer der Werte `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | Nein | Risikostufe, L0 bis L5. |
| `action` | einer der Werte `"accept"`, `"review"`, `"reject"`, `"resubmit"` | Nein |  |
| `assessment` | einer der Werte `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"` | Nein |  |
| `reason` | string oder null | Nein |  |

**questions: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `ai` | object | Nein |  |
| `edit` | object | Nein |  |
| `source` | object | Nein |  |

**ai: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `key` | einer der Werte `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"` | Nein |  |
| `basis` | einer der Werte `"verified"`, `"detected"`, `"declared"`, `null` | Nein | Worauf die Antwort beruht. |
| `strength` | einer der Werte `"strong"`, `"moderate"`, `"limited"`, `null` | Nein | Wie stark die Belege die Antwort stützen. |
| `likelihood` | integer oder null | Nein | Wahrscheinlichkeit einer KI-Erzeugung von 0 bis 100 in Schritten von 5 oder null. |

**edit: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `key` | einer der Werte `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"` | Nein |  |
| `basis` | einer der Werte `"verified"`, `"detected"`, `"declared"`, `null` | Nein | Worauf die Antwort beruht. |
| `strength` | einer der Werte `"strong"`, `"moderate"`, `"limited"`, `null` | Nein | Wie stark die Belege die Antwort stützen. |
| `regions` | integer | Nein | Anzahl der markierten Bereiche. |

**source: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `key` | string | Nein |  |
| `basis` | einer der Werte `"verified"`, `"detected"`, `"declared"`, `null` | Nein | Worauf die Antwort beruht. |
| `strength` | einer der Werte `"strong"`, `"moderate"`, `"limited"`, `null` | Nein | Wie stark die Belege die Antwort stützen. |
| `signer` | string oder null | Nein |  |
| `aiClaim` | boolean | Nein | Ob die eigenen Angaben der Datei eine KI-Erzeugung ausweisen. |

**generator: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `name` | string | Nein |  |
| `basis` | string | Nein | Wie der Generator identifiziert wurde. |

**regions: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Nein |  |
| `x` | integer | Nein |  |
| `y` | integer | Nein |  |
| `w` | integer | Nein |  |
| `h` | integer | Nein |  |
| `strength` | einer der Werte `"high"`, `"medium"` | Nein |  |

**provenance: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `credentials` | einer der Werte `"valid"`, `"unverified"`, `"issues"`, `"invalid"`, `"removed"`, `"none"` | Nein | Zustand der Content Credentials. |
| `signer` | string oder null | Nein |  |
| `software` | array von string | Nein | In den Angaben der Datei genannte Software. |
| `camera` | string oder null | Nein |  |
| `captured` | string oder null | Nein | In der Datei erfasster Aufnahmezeitpunkt, falls vorhanden. |

**report (DocumentReport): Felder**

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

**issuer: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `name` | string | Nein |  |
| `operator` | string | Nein |  |
| `verify` | string | Nein | Öffentliche Verifizierungsseite des Berichts. |

**file: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `name` | string oder null | Nein |  |
| `sha256` | string | Nein | SHA-256-Hash der geprüften Datei, hexadezimal. |
| `bytes` | integer | Nein |  |
| `format` | string | Nein |  |
| `pages` | integer | Nein |  |
| `textLayer` | einer der Werte `"present"`, `"partial"`, `"absent"` | Nein | Ob das Dokument eine Textebene enthält. |

**findings: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Nein |  |
| `basis` | einer der Werte `"verified"`, `"detected"`, `"declared"` | Nein |  |
| `strength` | einer der Werte `"strong"`, `"moderate"`, `"limited"` | Nein |  |
| `material` | boolean | Nein | Ob der Befund in die Stufe einfließt. |
| `pages` | array von integer | Nein |  |
| `images` | array von integer | Nein |  |

**text: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `status` | einer der Werte `"evaluated"`, `"insufficient_text"`, `"unsupported_language"`, `"no_text"` | Nein |  |
| `verdict` | einer der Werte `"ai_generated"`, `"mixed"`, `"human"`, `"inconclusive"` | Nein | Vorhanden, wenn der Status evaluated ist. |
| `words` | integer | Nein |  |
| `languages` | array von string | Nein |  |
| `passages` | integer | Nein | Anzahl der markierten Passagen. |

**images: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `n` | integer | Nein |  |
| `pages` | array von integer | Nein |  |
| `kind` | einer der Werte `"photo"`, `"graphic"` | Nein |  |
| `width` | integer | Nein |  |
| `height` | integer | Nein |  |
| `level` | einer der Werte `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"`, `null` | Nein |  |
| `assessment` | einer der Werte `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"`, `null` | Nein |  |
| `ai` | einer der Werte `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"`, `null` | Nein |  |
| `edit` | einer der Werte `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"`, `null` | Nein |  |

**structure: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `revisions` | integer oder null | Nein |  |
| `changedPages` | array von integer | Nein |  |
| `addedPages` | integer | Nein |  |
| `signatures` | integer | Nein |  |

**provenance: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `credentials` | string | Nein | Zustand der Content Credentials. |
| `signer` | string oder null | Nein |  |
| `aiClaim` | boolean | Nein | Ob die eigenen Angaben der Datei eine KI-Erzeugung ausweisen. |
| `software` | array von string | Nein |  |
| `created` | string oder null | Nein |  |
| `modified` | string oder null | Nein |  |
| `revisions` | integer oder null | Nein |  |
| `signed` | boolean oder null | Nein |  |

**error: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `code` | einer der Werte `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | Nein |  |
| `message` | string | Nein |  |

**progress: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `stage` | einer der Werte `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | Nein |  |
| `done` | integer | Nein | In der aktuellen Phase abgeschlossene Einheiten, falls bekannt; andernfalls 0. |
| `total` | integer | Nein | Einheiten in der aktuellen Phase, falls bekannt; andernfalls 0. |
| `position` | integer | Nein | Position in der Warteschlange, solange die Phase queued ist. |

**usage: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `amount` | integer | Nein | Berechneter Betrag in Cent; 0 bei Prüfungen aus dem kostenlosen Start und bei Fehlern. |
| `currency` | `"usd"` | Nein |  |
| `funding` | einer der Werte `"trial"`, `"balance"`, `null` | Nein |  |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `invalid_json` | 400 |
| `missing_parameter` | 400 |
| `unsupported_media_type` | 415 |
| `model_not_found` | 404 |
| `file_not_found` | 400 |
| `unsupported_file` | 415 |
| `invalid_file` | 422 |
| `file_too_large` | 413 |
| `too_many_pixels` | 413 |
| `too_many_pages` | 413 |
| `document_too_long` | 413 |
| `password_required` | 422 |
| `wrong_password` | 422 |
| `not_examinable` | 422 |
| `insufficient_balance` | 402 |
| `spend_limit_reached` | 402 |
| `service_unavailable` | 503 |
| `analysis_failed` | 502 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

**Anfrage: cURL**

```bash
curl https://api.fileverity.com/v1/analyses \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"model": "fvimg-2", "file": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB"}'
```

**Antwort**

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

### Analysen auflisten

`GET` `https://api.fileverity.com/v1/analyses`

Listet die Bild- und Dokumentanalysen Ihres Workspace auf, die neuesten zuerst. Testschlüssel erhalten immer eine leere Liste.

#### Parameter

| Name | Ort | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- | --- |
| `limit` | Abfrage | integer | Nein | Standardwert `20`. Minimum 1. Maximum 100. |
| `starting_after` | Abfrage | string | Nein | Cursor: der next_cursor der vorherigen Seite. |
| `type` | Abfrage | einer der Werte `"image"`, `"document"` | Nein |  |

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 200 | Eine Seite mit Analysen. | `AnalysisList` |
| 400 | Ungültige Anfrage. Fehlercodes: invalid_parameter. | `Error` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |

#### Antwort 200: AnalysisList

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `object` | `"list"` | Ja |  |
| `data` | array von `Analysis` | Ja |  |
| `has_more` | boolean | Ja |  |
| `next_cursor` | string oder null | Ja | Als starting_after übergeben, um die nächste Seite zu erhalten. |

**data: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja |  |
| `object` | `"analysis"` | Ja |  |
| `created` | integer | Ja | Unix-Zeitstempel. |
| `model` | string | Ja | Snapshot, der das Ergebnis erzeugt hat. |
| `livemode` | boolean | Ja |  |
| `status` | einer der Werte `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Ja |  |
| `file` | object | Ja |  |
| `report_id` | string oder null | Ja | Überprüfbare Berichts-ID, FV-XXXX-XXXX-XXXX. |
| `report_url` | string oder null | Ja | Öffentliche Verifizierungsseite des Berichts. |
| `summary` | `ImageSummary` oder `DocumentSummary` oder null | Ja | Die kurze, stabile Einstufung: eine ImageSummary für Bilder, eine DocumentSummary für Dokumente, null, bis die Analyse erfolgreich abgeschlossen ist. |
| `result` | object oder null | Ja | Vorhanden, sobald der Status succeeded ist, und bis das Ergebnis abläuft. |
| `error` | object oder null | Ja |  |
| `progress` | object oder null | Ja |  |
| `usage` | object | Ja |  |
| `metadata` | object oder null | Ja |  |
| `completed_at` | integer oder null | Ja |  |
| `expires_at` | integer oder null | Ja | Unix-Zeitstempel, nach dem das Ergebnis gelöscht wird. |

**file: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `name` | string oder null | Nein |  |
| `bytes` | integer oder null | Nein |  |
| `format` | string oder null | Nein |  |

**result: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `report` | `ImageReport` oder `DocumentReport` | Nein | Der vollständige Bericht. report.schema ist fileverity.report/1 für Bilder und fileverity.docpro/1 für Dokumente. |
| `stamped_at` | integer oder null | Nein | Unix-Zeitstempel des für den Bericht ausgestellten RFC-3161-Zeitstempels oder null. |

**error: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `code` | einer der Werte `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | Nein |  |
| `message` | string | Nein |  |

**progress: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `stage` | einer der Werte `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | Nein |  |
| `done` | integer | Nein | In der aktuellen Phase abgeschlossene Einheiten, falls bekannt; andernfalls 0. |
| `total` | integer | Nein | Einheiten in der aktuellen Phase, falls bekannt; andernfalls 0. |
| `position` | integer | Nein | Position in der Warteschlange, solange die Phase queued ist. |

**usage: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `amount` | integer | Nein | Berechneter Betrag in Cent; 0 bei Prüfungen aus dem kostenlosen Start und bei Fehlern. |
| `currency` | `"usd"` | Nein |  |
| `funding` | einer der Werte `"trial"`, `"balance"`, `null` | Nein |  |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `invalid_parameter` | 400 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

**Anfrage: cURL**

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

**Antwort**

```json
{
  "object": "list",
  "data": [
    {
      "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
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

### Analyse abrufen

`GET` `https://api.fileverity.com/v1/analyses/{id}`

Gibt die Analyse zurück, einschließlich ihres Ergebnisses, sobald sie erfolgreich ist und bis das Ergebnis abläuft.

#### Parameter

| Name | Ort | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- | --- |
| `id` | Pfad | string | Ja | Analyse-ID. |

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 200 | Die Analyse. | `Analysis` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 404 | Ressource nicht gefunden. Fehlercodes: not_found. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |

#### Antwort 200: Analysis

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja |  |
| `object` | `"analysis"` | Ja |  |
| `created` | integer | Ja | Unix-Zeitstempel. |
| `model` | string | Ja | Snapshot, der das Ergebnis erzeugt hat. |
| `livemode` | boolean | Ja |  |
| `status` | einer der Werte `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Ja |  |
| `file` | object | Ja |  |
| `report_id` | string oder null | Ja | Überprüfbare Berichts-ID, FV-XXXX-XXXX-XXXX. |
| `report_url` | string oder null | Ja | Öffentliche Verifizierungsseite des Berichts. |
| `summary` | `ImageSummary` oder `DocumentSummary` oder null | Ja | Die kurze, stabile Einstufung: eine ImageSummary für Bilder, eine DocumentSummary für Dokumente, null, bis die Analyse erfolgreich abgeschlossen ist. |
| `result` | object oder null | Ja | Vorhanden, sobald der Status succeeded ist, und bis das Ergebnis abläuft. |
| `error` | object oder null | Ja |  |
| `progress` | object oder null | Ja |  |
| `usage` | object | Ja |  |
| `metadata` | object oder null | Ja |  |
| `completed_at` | integer oder null | Ja |  |
| `expires_at` | integer oder null | Ja | Unix-Zeitstempel, nach dem das Ergebnis gelöscht wird. |

**file: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `name` | string oder null | Nein |  |
| `bytes` | integer oder null | Nein |  |
| `format` | string oder null | Nein |  |

**result: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `report` | `ImageReport` oder `DocumentReport` | Nein | Der vollständige Bericht. report.schema ist fileverity.report/1 für Bilder und fileverity.docpro/1 für Dokumente. |
| `stamped_at` | integer oder null | Nein | Unix-Zeitstempel des für den Bericht ausgestellten RFC-3161-Zeitstempels oder null. |

**error: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `code` | einer der Werte `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | Nein |  |
| `message` | string | Nein |  |

**progress: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `stage` | einer der Werte `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | Nein |  |
| `done` | integer | Nein | In der aktuellen Phase abgeschlossene Einheiten, falls bekannt; andernfalls 0. |
| `total` | integer | Nein | Einheiten in der aktuellen Phase, falls bekannt; andernfalls 0. |
| `position` | integer | Nein | Position in der Warteschlange, solange die Phase queued ist. |

**usage: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `amount` | integer | Nein | Berechneter Betrag in Cent; 0 bei Prüfungen aus dem kostenlosen Start und bei Fehlern. |
| `currency` | `"usd"` | Nein |  |
| `funding` | einer der Werte `"trial"`, `"balance"`, `null` | Nein |  |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

**Anfrage: cURL**

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

**Antwort**

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

### Analyse abbrechen

`POST` `https://api.fileverity.com/v1/analyses/{id}/cancel`

Bricht eine Dokumentanalyse ab, die noch verarbeitet wird, und gibt den reservierten Betrag frei. Bildanalysen können nach dem Erstellen nicht mehr abgebrochen werden.

#### Parameter

| Name | Ort | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- | --- |
| `id` | Pfad | string | Ja | Analyse-ID. |
| `Idempotency-Key` | Header | string | Nein | Eindeutiger Schlüssel mit bis zu 255 Zeichen. Wird die Anfrage innerhalb von 24 Stunden mit demselben Schlüssel und demselben Anfragetext wiederholt, gibt sie die erste Antwort mit dem Header idempotent-replayed: true zurück; derselbe Schlüssel mit einem anderen Anfragetext gibt 409 zurück. |

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 200 | Die abgebrochene Analyse. | `Analysis` |
| 400 | Ungültige Anfrage. Fehlercodes: invalid_parameter. | `Error` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 404 | Ressource nicht gefunden. Fehlercodes: not_found. | `Error` |
| 409 | Konflikt mit dem aktuellen Zustand. Fehlercodes: not_cancelable, idempotency_mismatch, idempotency_in_progress. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |

#### Antwort 200: Analysis

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja |  |
| `object` | `"analysis"` | Ja |  |
| `created` | integer | Ja | Unix-Zeitstempel. |
| `model` | string | Ja | Snapshot, der das Ergebnis erzeugt hat. |
| `livemode` | boolean | Ja |  |
| `status` | einer der Werte `"processing"`, `"succeeded"`, `"failed"`, `"canceled"` | Ja |  |
| `file` | object | Ja |  |
| `report_id` | string oder null | Ja | Überprüfbare Berichts-ID, FV-XXXX-XXXX-XXXX. |
| `report_url` | string oder null | Ja | Öffentliche Verifizierungsseite des Berichts. |
| `summary` | `ImageSummary` oder `DocumentSummary` oder null | Ja | Die kurze, stabile Einstufung: eine ImageSummary für Bilder, eine DocumentSummary für Dokumente, null, bis die Analyse erfolgreich abgeschlossen ist. |
| `result` | object oder null | Ja | Vorhanden, sobald der Status succeeded ist, und bis das Ergebnis abläuft. |
| `error` | object oder null | Ja |  |
| `progress` | object oder null | Ja |  |
| `usage` | object | Ja |  |
| `metadata` | object oder null | Ja |  |
| `completed_at` | integer oder null | Ja |  |
| `expires_at` | integer oder null | Ja | Unix-Zeitstempel, nach dem das Ergebnis gelöscht wird. |

**file: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `name` | string oder null | Nein |  |
| `bytes` | integer oder null | Nein |  |
| `format` | string oder null | Nein |  |

**result: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `report` | `ImageReport` oder `DocumentReport` | Nein | Der vollständige Bericht. report.schema ist fileverity.report/1 für Bilder und fileverity.docpro/1 für Dokumente. |
| `stamped_at` | integer oder null | Nein | Unix-Zeitstempel des für den Bericht ausgestellten RFC-3161-Zeitstempels oder null. |

**error: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `code` | einer der Werte `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"` | Nein |  |
| `message` | string | Nein |  |

**progress: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `stage` | einer der Werte `"queued"`, `"reading"`, `"analyzing"`, `"reporting"` | Nein |  |
| `done` | integer | Nein | In der aktuellen Phase abgeschlossene Einheiten, falls bekannt; andernfalls 0. |
| `total` | integer | Nein | Einheiten in der aktuellen Phase, falls bekannt; andernfalls 0. |
| `position` | integer | Nein | Position in der Warteschlange, solange die Phase queued ist. |

**usage: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `amount` | integer | Nein | Berechneter Betrag in Cent; 0 bei Prüfungen aus dem kostenlosen Start und bei Fehlern. |
| `currency` | `"usd"` | Nein |  |
| `funding` | einer der Werte `"trial"`, `"balance"`, `null` | Nein |  |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `not_found` | 404 |
| `not_cancelable` | 409 |
| `invalid_parameter` | 400 |
| `idempotency_mismatch` | 409 |
| `idempotency_in_progress` | 409 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

**Anfrage: cURL**

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

**Antwort**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "canceled",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": {
    "code": "canceled",
    "message": "The analysis was canceled. You were not charged."
  },
  "progress": null,
  "usage": {
    "amount": 0,
    "currency": "usd",
    "funding": null
  },
  "metadata": null,
  "completed_at": 1793700135,
  "expires_at": null
}
```

### PDF-Bericht herunterladen

`GET` `https://api.fileverity.com/v1/analyses/{id}/report.pdf`

Gibt den versiegelten PDF-Bericht einer erfolgreichen Analyse zurück, solange ihr Ergebnis aufbewahrt wird. Testschlüssel erhalten 404. Dokumentbelege wie Seitenbilder sind 3 Stunden nach der Analyse verfügbar; danach lässt das PDF sie weg, was durch x-evidence-included: false angezeigt wird.

#### Parameter

| Name | Ort | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- | --- |
| `id` | Pfad | string | Ja | Analyse-ID. |
| `locale` | Abfrage | einer der Werte `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `"vi"`, `"ar"` | Nein | Standardwert `"en"`. |

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 200 | Der PDF-Bericht. | PDF-Datei |
| 400 | Ungültige Anfrage. Fehlercodes: invalid_parameter. | `Error` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 404 | Ressource nicht gefunden. Fehlercodes: not_found. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `invalid_parameter` | 400 |
| `not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

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

## Modelle

### Modelle auflisten

`GET` `https://api.fileverity.com/v1/models`

Listet die für Ihren API-Schlüssel verfügbaren Modelle auf.

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 200 | Die verfügbaren Modelle. | `ModelList` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |

#### Antwort 200: ModelList

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `object` | `"list"` | Ja |  |
| `data` | array von `Model` | Ja |  |

**data: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja |  |
| `object` | `"model"` | Ja |  |
| `created` | integer | Ja | Unix-Zeitstempel des aktuellen Snapshots. |
| `owned_by` | string | Ja |  |
| `name` | string | Ja |  |
| `type` | einer der Werte `"image"`, `"document"`, `"text"` | Ja |  |
| `description` | string | Ja |  |
| `snapshot` | string | Ja | Datierter Snapshot, auf den die ID derzeit verweist. |
| `status` | einer der Werte `"available"`, `"preview"`, `"deprecated"` | Ja |  |
| `input` | object | Ja | Akzeptierte Eingabe. Bei Dateien sind Formate und Größenlimits aufgeführt, bei Text Sprachen und Längenlimits. |
| `output` | object | Ja |  |
| `pricing` | object | Ja |  |

**input: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `formats` | array von string | Nein |  |
| `max_bytes` | integer | Nein |  |
| `max_megapixels` | integer | Nein |  |
| `max_pages` | integer | Nein |  |
| `languages` | array von string | Nein |  |
| `min_words` | integer | Nein |  |
| `max_characters` | integer | Nein |  |

**output: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `schema` | string | Ja | Schema des Berichts in den Analyseergebnissen. |

**pricing: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `currency` | `"usd"` | Ja |  |
| `unit` | string | Ja |  |
| `unit_amount` | integer | Ja | Preis pro Einheit in Cent. |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

**Anfrage: cURL**

```bash
curl https://api.fileverity.com/v1/models \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Antwort**

```json
{
  "object": "list",
  "data": [
    {
      "id": "fvimg-2",
      "object": "model",
      "created": 1793318400,
      "owned_by": "fileverity",
      "name": "FVIMG V2",
      "type": "image",
      "description": "Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.",
      "snapshot": "fvimg-2-2026-10-30",
      "status": "available",
      "input": {
        "formats": [
          "jpeg",
          "png",
          "webp"
        ],
        "max_bytes": 10485760,
        "max_megapixels": 40
      },
      "output": {
        "schema": "fileverity.report/1"
      },
      "pricing": {
        "currency": "usd",
        "unit": "image",
        "unit_amount": 199
      }
    },
    {
      "id": "fvdoc-3",
      "object": "model",
      "created": 1793664000,
      "owned_by": "fileverity",
      "name": "FVDOC V3",
      "type": "document",
      "description": "Document fraud analysis. Evaluates AI-written text, embedded photos, edit history and signatures, and returns a verifiable report.",
      "snapshot": "fvdoc-3-2026-11-03",
      "status": "available",
      "input": {
        "formats": [
          "pdf",
          "docx",
          "doc",
          "rtf",
          "odt",
          "pptx",
          "txt"
        ],
        "max_bytes": 52428800,
        "max_pages": 100
      },
      "output": {
        "schema": "fileverity.docpro/1"
      },
      "pricing": {
        "currency": "usd",
        "unit": "document",
        "unit_amount": 599
      }
    },
    {
      "id": "fvdoc-3-text",
      "object": "model",
      "created": 1793664000,
      "owned_by": "fileverity",
      "name": "FVDOC V3 Text",
      "type": "text",
      "description": "AI-written text detection. Classifies plain text as AI-written, partly AI-written or human-written and marks the AI-written passages.",
      "snapshot": "fvdoc-3-text-2026-11-03",
      "status": "available",
      "input": {
        "languages": [
          "en",
          "fr",
          "de",
          "es",
          "zh"
        ],
        "min_words": 100,
        "max_characters": 100000
      },
      "output": {
        "schema": "fileverity.text-detection/1"
      },
      "pricing": {
        "currency": "usd",
        "unit": "1000_characters",
        "unit_amount": 14
      }
    }
  ]
}
```

### Modell abrufen

`GET` `https://api.fileverity.com/v1/models/{model}`

Ruft ein Modell anhand seiner ID oder Snapshot-ID ab.

#### Parameter

| Name | Ort | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- | --- |
| `model` | Pfad | string | Ja | Modell-ID oder Snapshot-ID. |

#### Antworten

| Status | Beschreibung | Antworttext |
| --- | --- | --- |
| 200 | Das Modell. | `Model` |
| 401 | Fehlender oder ungültiger API-Schlüssel. Fehlercodes: missing_api_key, invalid_api_key. | `Error` |
| 404 | Ressource nicht gefunden. Fehlercodes: model_not_found. | `Error` |
| 429 | Zu viele Anfragen. Fehlercodes: rate_limited. | `Error` |
| 500 | Interner Fehler; nicht berechnet. Fehlercodes: internal_error. | `Error` |

#### Antwort 200: Model

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja |  |
| `object` | `"model"` | Ja |  |
| `created` | integer | Ja | Unix-Zeitstempel des aktuellen Snapshots. |
| `owned_by` | string | Ja |  |
| `name` | string | Ja |  |
| `type` | einer der Werte `"image"`, `"document"`, `"text"` | Ja |  |
| `description` | string | Ja |  |
| `snapshot` | string | Ja | Datierter Snapshot, auf den die ID derzeit verweist. |
| `status` | einer der Werte `"available"`, `"preview"`, `"deprecated"` | Ja |  |
| `input` | object | Ja | Akzeptierte Eingabe. Bei Dateien sind Formate und Größenlimits aufgeführt, bei Text Sprachen und Längenlimits. |
| `output` | object | Ja |  |
| `pricing` | object | Ja |  |

**input: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `formats` | array von string | Nein |  |
| `max_bytes` | integer | Nein |  |
| `max_megapixels` | integer | Nein |  |
| `max_pages` | integer | Nein |  |
| `languages` | array von string | Nein |  |
| `min_words` | integer | Nein |  |
| `max_characters` | integer | Nein |  |

**output: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `schema` | string | Ja | Schema des Berichts in den Analyseergebnissen. |

**pricing: Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `currency` | `"usd"` | Ja |  |
| `unit` | string | Ja |  |
| `unit_amount` | integer | Ja | Preis pro Einheit in Cent. |

#### Fehlercodes

| Code | Status |
| --- | --- |
| `model_not_found` | 404 |
| `missing_api_key` | 401 |
| `invalid_api_key` | 401 |
| `rate_limited` | 429 |
| `internal_error` | 500 |

#### Beispiel

**Anfrage: cURL**

```bash
curl https://api.fileverity.com/v1/models/fvimg-2 \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Antwort**

```json
{
  "id": "fvimg-2",
  "object": "model",
  "created": 1793318400,
  "owned_by": "fileverity",
  "name": "FVIMG V2",
  "type": "image",
  "description": "Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.",
  "snapshot": "fvimg-2-2026-10-30",
  "status": "available",
  "input": {
    "formats": [
      "jpeg",
      "png",
      "webp"
    ],
    "max_bytes": 10485760,
    "max_megapixels": 40
  },
  "output": {
    "schema": "fileverity.report/1"
  },
  "pricing": {
    "currency": "usd",
    "unit": "image",
    "unit_amount": 199
  }
}
```

## Webhook-Ereignisse

Fileverity sendet diese Ereignisse an Ihre Webhook-Endpunkte. Die Regeln für Verifizierung und Zustellung stehen unter [Webhooks](https://fileverity.com/de/docs/webhooks.md).

### Ereignis analysis.completed

Wird gemäß der Spezifikation Standard Webhooks an Ihre Webhook-Endpunkte zugestellt: mit den Headern webhook-id, webhook-timestamp und webhook-signature (v1,<base64 HMAC-SHA256 von id.timestamp.body>, mit dem Base64-Teil Ihres whsec_-Secrets als Schlüssel). Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx; fehlgeschlagene Zustellungen werden 3 Tage lang mit exponentiellem Backoff wiederholt.

#### Anfragetext: application/json, erforderlich

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja | Wird auch als Header webhook-id gesendet; damit lassen sich Wiederholungen deduplizieren. |
| `object` | `"event"` | Ja |  |
| `type` | einer der Werte `"analysis.completed"`, `"analysis.failed"`, `"balance.low"` | Ja |  |
| `created` | integer | Ja | Unix-Zeitstempel. |
| `data` | `Analysis` oder `BalanceLow` | Ja | Ereignisse vom Typ analysis.* enthalten dasselbe Objekt wie GET /analyses/{id}, wobei result immer null ist; rufen Sie das Ergebnis über diesen Endpunkt ab. Ereignisse vom Typ balance.low enthalten das Guthaben und die Schwelle in Cent. |

**data (BalanceLow): Felder**

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `balance` | integer | Ja | Guthaben in Cent. |
| `threshold` | integer | Ja | Warnschwelle in Cent. |

### Ereignis analysis.failed

Wird gemäß der Spezifikation Standard Webhooks an Ihre Webhook-Endpunkte zugestellt: mit den Headern webhook-id, webhook-timestamp und webhook-signature (v1,<base64 HMAC-SHA256 von id.timestamp.body>, mit dem Base64-Teil Ihres whsec_-Secrets als Schlüssel). Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx; fehlgeschlagene Zustellungen werden 3 Tage lang mit exponentiellem Backoff wiederholt.

#### Anfragetext: application/json, erforderlich

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja | Wird auch als Header webhook-id gesendet; damit lassen sich Wiederholungen deduplizieren. |
| `object` | `"event"` | Ja |  |
| `type` | einer der Werte `"analysis.completed"`, `"analysis.failed"`, `"balance.low"` | Ja |  |
| `created` | integer | Ja | Unix-Zeitstempel. |
| `data` | `Analysis` oder `BalanceLow` | Ja | Ereignisse vom Typ analysis.* enthalten dasselbe Objekt wie GET /analyses/{id}, wobei result immer null ist; rufen Sie das Ergebnis über diesen Endpunkt ab. Ereignisse vom Typ balance.low enthalten das Guthaben und die Schwelle in Cent. |

### Ereignis balance.low

Wird gemäß der Spezifikation Standard Webhooks an Ihre Webhook-Endpunkte zugestellt: mit den Headern webhook-id, webhook-timestamp und webhook-signature (v1,<base64 HMAC-SHA256 von id.timestamp.body>, mit dem Base64-Teil Ihres whsec_-Secrets als Schlüssel). Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx; fehlgeschlagene Zustellungen werden 3 Tage lang mit exponentiellem Backoff wiederholt.

#### Anfragetext: application/json, erforderlich

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `id` | string | Ja | Wird auch als Header webhook-id gesendet; damit lassen sich Wiederholungen deduplizieren. |
| `object` | `"event"` | Ja |  |
| `type` | einer der Werte `"analysis.completed"`, `"analysis.failed"`, `"balance.low"` | Ja |  |
| `created` | integer | Ja | Unix-Zeitstempel. |
| `data` | `Analysis` oder `BalanceLow` | Ja | Ereignisse vom Typ analysis.* enthalten dasselbe Objekt wie GET /analyses/{id}, wobei result immer null ist; rufen Sie das Ergebnis über diesen Endpunkt ab. Ereignisse vom Typ balance.low enthalten das Guthaben und die Schwelle in Cent. |

**OpenAPI**

```bash
curl https://api.fileverity.com/v1/openapi.json
```