Fileverity-API-Dokumentation
Bilderkennungen
Mit POST /images/detections erkennen Sie, ob ein ganzes Bild mit KI erzeugt wurde. Ein synchroner Aufruf: Felder von Anfrage und Antwort, Antwortwerte, Limits und Abrechnung.
POST /images/detections führt die KI-Erkennung für Bilder aus. Mit vereye-2-detect sagt sie Ihnen, ob ein ganzes Bild mit KI erzeugt wurde, auf Basis derselben Modelle, Content Credentials, KI-Kennzeichnungen und Wasserzeichen wie der Bildforensik-Bericht (vereye-2); beide geben daher dieselbe Antwort zur KI-Erzeugung. Der Aufruf ist synchron: Das Ergebnis steht in der Antwort.
Lokale Bearbeitungen, auch KI-Änderungen an einem Teil eines Fotos, werden nicht untersucht, und es gibt weder Berichts-ID noch PDF. Für Bearbeitungen, Herkunft und einen Nachweis, den jeder verifizieren kann, erstellen Sie eine Analyse mit vereye-2.
curl https://api.fileverity.com/v1/images/detections \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -H "Idempotency-Key: 6b9d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e11" \ -F file=@photo.jpgimport { readFile } from "node:fs/promises";import { randomUUID } from "node:crypto"; const form = new FormData();form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg"); const response = await fetch("https://api.fileverity.com/v1/images/detections", { method: "POST", headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Idempotency-Key": randomUUID() }, body: form,});const detection = await response.json();console.log(detection.verdict, detection.ai);import osimport uuidimport requests response = requests.post( "https://api.fileverity.com/v1/images/detections", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())}, files={"file": open("photo.jpg", "rb")},)detection = response.json()print(detection["verdict"], detection["ai"])Anfragetext
Senden Sie das Bild als multipart/form-data im Feld file, bis zu 4 MB. Größere Bilder, bis zu 10 MB, laden Sie zuerst mit POST /files hoch und senden dann JSON:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
file | file oder string | Ja | Das Bild in einer Multipart-Anfrage oder die ID eines hochgeladenen Bildes in einer JSON-Anfrage. JPEG, PNG, WEBP, bis 40 Megapixel. Eine Datei-ID wird durch die Prüfung verbraucht. |
model | string | Nein | Standard vereye-2-detect. Akzeptiert die Modell-ID oder ihre Snapshot-ID vereye-2-detect-2026-10-30. |
Unbekannte Felder werden mit invalid_parameter abgelehnt.
Antwort
{ "id": "idet_8Hk2pQ4vN9sL1xR7cW3mY6zB", "object": "image.detection", "created": 1794096000, "model": "vereye-2-detect-2026-10-30", "livemode": true, "verdict": "ai_generated", "ai": { "key": "very_likely", "basis": "detected", "strength": "strong", "likelihood": 100 }, "generator": null, "signals": [ { "id": "model_1", "state": "ai" }, { "id": "model_2", "state": "ai" }, { "id": "credentials", "state": "none" }, { "id": "watermark", "state": "none" }, { "id": "label", "state": "none" }, { "id": "tool_data", "state": "none" }, { "id": "camera", "state": "none" } ], "regions": [ { "x": 0, "y": 0, "w": 576, "h": 512, "level": 3 }, { "x": 576, "y": 0, "w": 384, "h": 512, "level": 3 }, { "x": 960, "y": 0, "w": 576, "h": 512, "level": 2 }, { "x": 0, "y": 512, "w": 576, "h": 512, "level": 3 }, { "x": 576, "y": 512, "w": 384, "h": 512, "level": 3 }, { "x": 960, "y": 512, "w": 576, "h": 512, "level": 3 } ], "candidates": [ { "name": "Midjourney", "score": 0.65 }, { "name": "OpenAI", "score": 0.25 } ], "quality": { "overall": "fair", "resolution": "good", "compression": "fair", "metadata": "fair", "distribution": "good" }, "limits": [ "no_metadata" ], "image": { "width": 1536, "height": 1024, "format": "jpeg", "jpeg_quality": 85 }, "usage": { "credits": 4 }}| Feld | Typ | Beschreibung |
|---|---|---|
id | string | ID der Bilderkennung mit dem Präfix idet_. |
object | string | Immer image.detection. |
created | integer | Unix-Zeitstempel. |
model | string | Snapshot, der das Ergebnis erzeugt hat. |
livemode | boolean | false bei Testschlüsseln. |
verdict | string | ai_generated: Das Bild wurde mit KI erzeugt. no_ai_signs: Nichts deutet auf KI-Erzeugung hin. inconclusive: Die Belege reichen für eine Entscheidung nicht aus. |
ai | object | Die Antwort zur KI-Erzeugung, mit denselben Werten wie questions.ai im Bildbericht. |
generator | object oder null | Der Generator, den die Datei über Content Credentials, Metadaten oder ein Wasserzeichen angibt, mit name und basis. null, wenn die Datei keinen nennt. |
signals | array | Die Prüfungen hinter der Antwort, jeweils mit id und state. Siehe Signale. |
regions | Array oder null | Ein grobes Raster über dem Bild. Jede Zelle hat x, y, w und h in Pixeln des angezeigten Bildes sowie ein level von 0 bis 3 für die Stärke der Generierungsmerkmale. null, wenn das Bild für ein Raster zu klein ist. |
candidates | array | Bis zu drei Generatorfamilien, deren Pixelmerkmalen das Bild am ähnlichsten ist, jeweils mit name und einem score von 0 bis 1. Leer, außer die Einstufung ist ai_generated. |
quality | object oder null | Wie gut sich die Datei analysieren lässt: overall, resolution, compression, metadata und distribution, jeweils good, fair oder poor. |
limits | array | Was das Ergebnis einschränkt: low_resolution, heavy_compression, platform_copy, no_metadata oder models_disagree. |
image | object | width und height wie angezeigt, format und jpeg_quality, die geschätzte JPEG-Qualität oder null. |
usage | object | Belastete credits. |
Die Antwort lesen
| `ai.key` | `verdict` | Bedeutung |
|---|---|---|
labelled | ai_generated | Content Credentials, eine KI-Kennzeichnung oder ein Wasserzeichen weisen auf KI-Erzeugung hin. ai.basis ist verified bei vertrauenswürdigen Credentials, sonst declared oder detected. |
very_likely, suspected | ai_generated | Die Pixel deuten auf KI-Erzeugung hin, deutlich oder mit gewissen Widersprüchen. |
undecided | inconclusive | Die Signale sind schwach oder widersprechen sich. |
low, very_low | no_ai_signs | Weder die Pixel noch die Metadaten deuten auf KI-Erzeugung hin. |
ai.strength ist strong, moderate oder limited und gibt an, wie stark die Belege die Antwort stützen. ai.likelihood reicht in Schritten von 5 von 0 bis 100 und ist bei labelled null.
no_ai_signs zeigt nicht, dass ein Foto echt oder unbearbeitet ist. Die KI-Erkennung für Bilder sucht nicht nach Bearbeitungen. Hängt eine Entscheidung davon ab, führen Sie einen Bildforensik-Bericht aus und lassen Sie das Ergebnis von einer Person prüfen.
Signale
signals listet jede durchgeführte Prüfung auf, damit Sie sehen, worauf die Antwort beruht. Ein state von ai deutet auf KI-Erzeugung hin.
| `id` | `state` | Prüfung |
|---|---|---|
model_1, model_2 | ai, unclear, clear, unavailable | Zwei unabhängig trainierte Modelle, die die Pixel analysieren. |
credentials | ai, ai_unverified, other, none | Content Credentials (C2PA). ai_unverified: Die Credentials weisen KI-Erzeugung aus, ihr Aussteller ließ sich aber nicht verifizieren. other: Credentials sind vorhanden und enthalten keine Angabe zu KI-Erzeugung. |
watermark | ai, none, unavailable | Unsichtbare Wasserzeichen, die Open-Source-Generierungstools in die Pixel einbetten. |
label | ai, none | Eine Angabe zur KI-Erzeugung in den Metadaten, etwa der IPTC-Digitalquellentyp. |
tool_data | ai, none | In der Datei gespeicherte Prompts, Parameter oder Generatornamen. |
camera | present, none | Kamerahersteller, Modell und Belichtungsdaten. Sie lassen sich ändern und werden von diesem Endpunkt nicht verifiziert. |
regions zeigt, wo die Generierungsmerkmale am stärksten sind. Zellen mit Stufe 3 tragen starke Merkmale. Ist die Einstufung no_ai_signs und liegen einzelne Zellen auf Stufe 3, kann ein Teil des Bildes mit KI erzeugt oder bearbeitet worden sein: Dieser Endpunkt untersucht keine lokalen Bearbeitungen, führen Sie dafür einen Bildforensik-Bericht aus.
candidates ist ein Hinweis, keine Identifizierung. Das Feld ordnet Generatorfamilien danach, wie ähnlich ihnen die Pixelmerkmale sind, und ein Generator außerhalb der Referenzmenge erscheint als nächster Treffer. Verlassen Sie sich auf generator, wenn die Datei das Tool selbst nennt.
Abrechnung
- Die KI-Erkennung für Bilder kostet 4 Credits pro Bild.
- Ein Bildforensik-Bericht für dasselbe Bild im selben Workspace innerhalb von 7 Tagen kostet 36 statt 40 Credits: Die Credits der Erkennung werden einmal angerechnet. Die Analyse weist die Belastung in
usage.creditsaus. - Anfragen, die vor der Auswertung abgelehnt werden, werden nicht berechnet: ungültige Parameter, nicht unterstützte oder beschädigte Dateien, Größenlimits und Ähnliches. Eine Prüfung, die im Dienst fehlschlägt (
service_unavailable,analysis_failed), wird freigegeben und nicht berechnet. - Reichen die Credits nicht aus, wird
insufficient_balance(402) zurückgegeben.
Was gespeichert wird
Das Bild wird geprüft und gelöscht. Fileverity speichert das Ergebnis ohne das Bild (Einstufung, Antwort, Generator, Signale, Bereiche, Kandidaten, Qualität, Abmessungen, den SHA-256-Fingerabdruck der Datei und die Nutzung) 7 Tage lang, damit die Konsole es anzeigen und die Nutzung abgerechnet und geprüft werden kann. Eine wiederholte Anfrage mit demselben Idempotency-Key erhält 24 Stunden lang das gespeicherte Ergebnis. Bilderkennungen sind synchron: Sie erscheinen nicht in GET /analyses und senden keine Webhook-Ereignisse. Testschlüssel speichern nichts. Siehe Datenaufbewahrung und Sicherheit.
Fehler
| Code | Status | Ursache |
|---|---|---|
missing_parameter | 400 | Das Feld file fehlt. |
invalid_parameter | 400 | Ein Feld hat den falschen Typ, es wurde ein unbekanntes Feld gesendet, das Modell ist kein Modell für Bilderkennung, oder der Idempotency-Key ist ungültig. |
file_not_found | 400 | Die Datei-ID ist unbekannt, abgelaufen oder bereits verwendet. |
unsupported_file, invalid_file | 415, 422 | Die Datei ist kein JPEG-, PNG- oder WebP-Bild oder ist beschädigt. |
file_too_large, too_many_pixels | 413 | Die Multipart-Datei überschreitet 4 MB, die hochgeladene Datei überschreitet 10 MB oder das Bild überschreitet 40 Megapixel. |
unsupported_media_type, invalid_json | 415, 400 | Der Anfragetext ist weder multipart/form-data noch ein JSON-Objekt. |
model_not_found | 404 | Das model ist unbekannt. |
insufficient_balance, spend_limit_reached | 402 | Das Guthaben oder das monatliche Limit des Schlüssels reicht für die Anfrage nicht aus. |
idempotency_mismatch, idempotency_in_progress | 409 | Der Idempotency-Key wurde mit einem anderen Anfragetext verwendet, oder seine erste Anfrage läuft noch. |
service_unavailable, analysis_failed | 503, 502 | Der Dienst für die Textprüfung ist vorübergehend nicht verfügbar oder ausgelastet. Es wird nichts berechnet; versuchen Sie es erneut. Bei service_unavailable enthält die Antwort den Header retry-after. |
Senden Sie einen Idempotency-Key, damit ein erneuter Versuch nach einem Timeout nicht doppelt berechnet wird. Siehe Idempotenz.