Fileverity-API-Dokumentation

Dateien

Bilder und Dokumente zu Fileverity hochladen: Multipart für Dateien bis 4 MB, Upload über vorsignierte URL für Dateien bis 50 MB. Dateiobjekt, Limits und Aufbewahrung.

Als Markdown ansehenAktualisiert am 2026-11-04

Bilder und Dokumente werden in zwei Schritten geprüft. Zuerst laden Sie die Datei mit POST /files hoch und erhalten eine Datei-ID. Dann erstellen Sie eine Analyse, die auf diese ID verweist. Text braucht keine Datei; verwenden Sie dafür Textprüfungen.

Unterstützte Dateien

	Bilder (fvimg-2)	Dokumente (fvdoc-3)
Formate	`jpeg`, `png`, `webp`	`pdf`, `docx`, `doc`, `rtf`, `odt`, `pptx`, `txt`
Maximale Größe	10 MB	50 MB
Weitere Limits	40 Megapixel	100 Seiten

Zwei Wege zum Hochladen

Methode	Anfrage	Größe	Dateistatus in der Antwort
Multipart	`multipart/form-data` mit dem Feld `file`	Bis zu 4 MB	`uploaded`
Vorsignierte URL	JSON mit `filename`, `content_type` und `bytes`, danach ein `PUT` der Bytes	Bis zu 50 MB	`pending`, bis die Bytes eingetroffen sind

Für Bilder gilt unabhängig von der Methode die oben genannte maximale Bildgröße.

Multipart-Upload

Senden Sie Dateien bis 4 MB als multipart/form-data im Feld file. Das Format wird aus dem Dateiinhalt erkannt, nicht aus dem Namen oder dem angegebenen Typ.

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

import { readFile } from "node:fs/promises"; const form = new FormData();form.append("file", new Blob([await readFile("claim-photo.jpg")]), "claim-photo.jpg");const response = await fetch("https://api.fileverity.com/v1/files", {  method: "POST",  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },  body: form,});const file = await response.json();

import osimport requests response = requests.post(    "https://api.fileverity.com/v1/files",    headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]},    files={"file": open("claim-photo.jpg", "rb")},)file = response.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}

Upload über vorsignierte URL

Fordern Sie für Dateien über 4 MB bis 50 MB eine Upload-URL an und senden Sie die Bytes dann direkt an den Speicher.

POST /files mit einem JSON-Anfragetext: filename (optional), content_type und die genaue Größe in bytes. Die Antwort enthält status: pending und ein Objekt upload.
Senden Sie die Bytes der Datei vor upload.expires_at per PUT an upload.url und verwenden Sie dabei die Header aus upload.headers. Für diese Anfrage ist kein Header Authorization nötig.
Fragen Sie optional GET /files/{id} ab, bis status den Wert uploaded hat.
Erstellen Sie die Analyse mit der Datei-ID.

FILE=$(curl -s https://api.fileverity.com/v1/files \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -d '{"filename": "contract.pdf", "content_type": "application/pdf", "bytes": 18874368}') UPLOAD_URL=$(echo "$FILE" | jq -r .upload.url)FILE_ID=$(echo "$FILE" | jq -r .id) curl -X PUT "$UPLOAD_URL" \  -H "content-type: application/pdf" \  --data-binary @contract.pdf

import { readFile } from "node:fs/promises"; const bytes = await readFile("contract.pdf");const response = await fetch("https://api.fileverity.com/v1/files", {  method: "POST",  headers: {    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,    "Content-Type": "application/json",  },  body: JSON.stringify({ filename: "contract.pdf", content_type: "application/pdf", bytes: bytes.length }),});const file = await response.json(); await fetch(file.upload.url, { method: "PUT", headers: file.upload.headers, body: bytes });

import osimport requests data = open("contract.pdf", "rb").read()response = requests.post(    "https://api.fileverity.com/v1/files",    headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]},    json={"filename": "contract.pdf", "content_type": "application/pdf", "bytes": len(data)},)file = response.json() requests.put(file["upload"]["url"], headers=file["upload"]["headers"], data=data)

{  "id": "file_Pw3mY6zB8Hk2pQ4vN9sL1xR7",  "object": "file",  "filename": "contract.pdf",  "bytes": 18874368,  "content_type": "application/pdf",  "status": "pending",  "livemode": true,  "created": 1793700000,  "expires_at": 1793786400,  "upload": {    "url": "https://example.private.blob.vercel-storage.com/f/0d6f1c2e-7b1a-4c53-9a0e-5e8a41b3c7d2?signature=...",    "method": "PUT",    "headers": {      "content-type": "application/pdf"    },    "expires_at": 1793703600  }}

Die gezeigte URL ist gekürzt. Verwenden Sie die URL aus Ihrer Antwort unverändert. Senden Sie den Header content-type genau so, wie er in upload.headers zurückgegeben wird.

Akzeptierte Content-Types

Art	Content-Types
Bilder	`image/jpeg`, `image/png`, `image/webp`
Dokumente	`application/pdf`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/msword`, `application/rtf`, `application/vnd.oasis.opendocument.text`, `application/vnd.openxmlformats-officedocument.presentationml.presentation`, `text/plain`

Das Dateiobjekt

Feld	Typ	Beschreibung
`id`	string	Datei-ID mit dem Präfix `file_`.
`object`	string	Immer `file`.
`filename`	string oder null	Bereinigter Dateiname.
`bytes`	integer oder null	Größe in Bytes.
`content_type`	string	Erkannter oder angegebener Content-Type.
`status`	string	`pending`, bis die hochgeladenen Bytes eingetroffen sind, danach `uploaded`.
`livemode`	boolean	`false` bei Dateien, die mit einem Testschlüssel erstellt wurden. Dateien sind nach Modus getrennt.
`created`	integer	Unix-Zeitstempel.
`expires_at`	integer	Unix-Zeitstempel, nach dem die Datei gelöscht wird.
`upload`	object	Nur in der Antwort auf eine JSON-Upload-Anfrage: `url`, `method` (`PUT`), `headers` und `expires_at`.

Aufbewahrung

Eine Datei wird höchstens 24 Stunden aufbewahrt (siehe expires_at) und dann gelöscht.
Eine Datei wird gelöscht, sobald eine Analyse mit ihr beginnt. Jede hochgeladene Datei kann nur für eine Analyse verwendet werden; laden Sie sie erneut hoch, um sie noch einmal zu prüfen.
DELETE /files/{id} entfernt eine Datei und ihre gespeicherten Bytes früher.
Ein Workspace kann pro Modus gleichzeitig bis zu 50 nicht abgelaufene Dateien und 200 MB enthalten. Darüber hinaus schlagen Uploads mit pending_files_limit fehl (HTTP 429, ohne retry-after), bis Dateien verwendet oder gelöscht werden oder ablaufen.
Eine unbekannte, abgelaufene oder bereits verwendete Datei-ID liefert beim Erstellen einer Analyse file_not_found und beim Abrufen oder Löschen not_found. file_not_found wird auch zurückgegeben, wenn der Upload an upload.url noch nicht abgeschlossen ist; warten Sie daher, bis GET /files/{id} den Status uploaded zeigt.

Fehler

Code	Status	Ursache
`missing_parameter`	400	Kein Feld `file` im Multipart-Anfragetext.
`unsupported_media_type`	415	Der Anfragetext ist weder `multipart/form-data` noch JSON.
`unsupported_file`	415	Das Format wird nicht unterstützt.
`invalid_file`	422	Die Datei ist leer, beschädigt oder nicht lesbar.
`file_too_large`	413	Eine Multipart-Datei über 4 MB oder `bytes` über 50 MB.
`invalid_parameter`	400	Ein JSON-Feld fehlt, hat den falschen Typ oder ist unbekannt.
`invalid_json`	400	Der JSON-Anfragetext ist kein Objekt.
`pending_files_limit`	429	Zu viele nicht abgelaufene Uploads im Workspace. Wird ohne Header `retry-after` gesendet.
`idempotency_mismatch`, `idempotency_in_progress`	409	Der `Idempotency-Key` wurde mit einer anderen Anfrage verwendet, oder seine erste Anfrage läuft noch.

Testschlüssel validieren Uploads, speichern die Bytes aber nicht. Eine JSON-Upload-Anfrage mit einem Testschlüssel liefert ein Test-Upload-Objekt (upload.test ist true, die Datei ist bereits uploaded): Es gibt nichts per PUT zu senden.