API-Dokumentation

API zur KI-Bilderkennung

Vollständige Dokumentation zur Integration der TruthScan-KI-Bilderkennungs-API in Ihre Anwendungen.

Ohne Code testen: Besuchen Sie unseren FastAPI-Endpunkt: https://detect-image.truthscan.com/docs

Bevorzugen Sie eine Client-Bibliothek? Nutzen Sie unsere offiziellen SDKs, anstatt die REST-API direkt aufzurufen. Client-SDK-Dokumentation anzeigen

Authentifizierung

TruthScan nutzt API-Schlüssel. Ihren Schlüssel finden Sie oben auf der Seite im Entwicklerportal.

Der API-Schlüssel wird in API-Anfragen im JSON-Body mitgesendet (außer Endpunkte mit reiner Header-Authentifizierung, z. B. check-user-credits):

{
  "key": "YOUR API KEY GOES HERE"
}

Ersetzen Sie YOUR API KEY GOES HERE durch Ihren persönlichen API-Schlüssel.

Rate Limits

Die API erzwingt pro API-Schlüssel ein Minutenbudget für Anfragen. Schwerere Schreib-Endpunkte kosten mehr als leichtere Lese-Endpunkte. Der Standardwert beträgt 60 Anfragen pro Minute – kontaktieren Sie uns, wenn Sie ein höheres Limit benötigen.

Endpunkt-Gewichte

Jeder Aufruf zieht sein Gewicht von Ihrem Minutenbudget ab:

Endpunkt	Typ	Gewicht
POST /detect	Schreiben	1
POST /bulk-upload	Schreiben	1
GET /get-presigned-url	Lesen	0.2
GET /check-user-credits	Lesen	0.2
POST /heatmap/{id}	Lesen	0.2
POST /preview/{id}	Lesen	0.2
POST /query	Lesen	Nicht limitiert
GET /health	Lesen	Nicht limitiert

Beispiel: Mit einem Budget von 60/Minute können Sie bis zu 60 Schreibaufrufe, bis zu ~300 Leseaufrufe oder eine beliebige Mischung senden, solange die gewichtete Summe ≤ 60 pro Minute bleibt.

Gedrosselte Antwort (HTTP 429)

Wenn Sie Ihr Minutenbudget überschreiten, liefert die API:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 3
X-RateLimit-Retry-After: 3
Content-Type: application/json

{
  "error": "Too many requests"
}

Rate-Limit-Antwort-Header

X-RateLimit-Limit – Ihr Minutenkontingent.
X-RateLimit-Remaining – verbleibende Aufrufe in der aktuellen Minute (nach dieser Anfrage).
X-RateLimit-Reset – (nur bei 429) Sekunden, bis Sie wieder eine Schreibanfrage senden können.
X-RateLimit-Retry-After – (nur bei 429) gleicher Wert wie X-RateLimit-Reset, im Retry-After-Stil.

Empfohlenes Client-Verhalten

Beobachten Sie X-RateLimit-Remaining bei erfolgreichen Antworten und takten Sie Ihre Anfragen entsprechend.
Bei einem 429 mindestens X-RateLimit-Retry-After Sekunden warten – mit Exponential Backoff und Jitter.
Bevorzugen Sie für Stapelverarbeitung POST /bulk-upload (ein Aufruf verarbeitet bis zu 50 Bilder) gegenüber vielen parallelen /detect-Aufrufen.

KI-Bilderkennung

Erkennen (3-Schritte-Ablauf)

Der Ablauf der KI-Bilderkennung besteht aus folgenden Schritten:

Vorsignierte Upload-URL abrufen
Bild hochladen
Bild zur Erkennung einreichen

1. Vorsignierte Upload-URL abrufen

Fordern Sie zunächst eine vorsignierte URL von der API an. Damit können Sie Ihre Bilddatei sicher auf den Speicher hochladen.

Unterstützte Dateiformate

JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG, PDF

Dateiname

Entfernen Sie Leerzeichen im Bilddateinamen, wenn Sie eine vorsignierte URL anfordern.

Bei PDF-Dateien wird nur das erste Bild erkannt (Einzeldatei-Flow).

Verwenden Sie an diesem Endpunkt einen .zip-Dateinamen, wenn Sie ein ZIP per Bulk-Upload einreichen möchten.

Abfrageparameter

file_name (erforderlich) — Originaldateiname; der Server kann ihn normalisieren (Leerzeichen und unsichere Zeichen werden angepasst). Für Bulk-Upload die Erweiterung .zip verwenden.
expiration (optional) — Gültigkeitsdauer der vorsignierten URL in Sekunden (Standard: 3600).

GET https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg

Beispielanfrage

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg' \
--header 'apikey: YOUR API KEY GOES HERE'

Beispielantwort

{
  "status": "success",
  "presigned_url": "https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...",
  "file_path": "uploads/example.jpg",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

document_id ist eine neue UUID für diese Upload-Anfrage (Korrelation/Logging). Die id für /detect oder /bulk-upload wird beim Aufruf dieser Endpunkte vergeben, sofern Sie keine optionale id bei /detect übergeben.

HTTP-Antworten

Erforderlicher Header: apikey: YOUR-API-KEY-GOES-HERE

Status	Body	Wann
200	JSON: status, presigned_url, file_path, document_id	Erfolg
400	{"error": "..."}	Nicht unterstützter Dateityp / ungültige Parameter
403	{"error": "..."}	Ungültiger API-Schlüssel
404	{"error": "..."}	TruthScan-Schlüsselvalidierung fehlgeschlagen
500	{"error": "..."}	Serverfehler

2. Bild hochladen

Laden Sie mit der bereitgestellten presigned_url per PUT hoch. Setzen Sie den Content-Type passend zu Ihrem Bildformat.

Dateiname

Entfernen Sie Leerzeichen im Dateinamen beim Hochladen.

Content-Type exakt zur Dateiendung setzen

image/jpeg: jpg, jpeg, jfif
image/png: png
image/webp: webp
image/heic: heic
image/heif: heif
image/avif: avif
image/bmp: bmp
image/tiff: tiff, tif
image/gif: gif
image/svg+xml: svg
application/pdf: pdf

Häufige Fehler vermeiden

Nicht image/jpg verwenden (falsch). Verwenden Sie image/jpeg.
Datei und Header nicht mischen (z. B. .png mit image/jpeg).
Endung nicht ändern, ohne den Header anzupassen (und umgekehrt).
Keine Leerzeichen in Dateinamen beim Anfordern/Hochladen.

Beispielanfrage

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...' \
  --header 'Content-Type: image/jpeg' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg'

Weitere Upload-Beispiele (PNG, PDF, SVG)

curl -X PUT '<PRESIGNED_URL_FOR_example.png>' \
  --header 'Content-Type: image/png' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.png'

curl -X PUT '<PRESIGNED_URL_FOR_example.pdf>' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.pdf'

curl -X PUT '<PRESIGNED_URL_FOR_example.svg>' \
  --header 'Content-Type: image/svg+xml' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.svg'

Dateigrößen

Mindestgröße: 1 KB
Maximalgröße: 10 MB

Format während des Uploads konsistent halten. Erfolgreicher Upload liefert HTTP 200.

Storage-PUT-Antwort

Schritt 2 ist ein direkter PUT in den Objektspeicher (presigned URL), nicht unsere API. Einzelbild- und ZIP-Massen-Uploads verhalten sich gleich.

Bei Erfolg: HTTP 200 mit leerem Body — beabsichtigt. Es gibt kein JSON zum Parsen.

Nach PUT auf presigned_url: res.ok (Status 200–299) als Erfolg werten. Bei Erfolg response.json() nicht aufrufen — leerer Body ist erwartet. Fehler nur bei Nicht-2xx-Antworten melden.

3. Bild zur KI-Erkennung einreichen

Nach dem Upload reichen Sie die Erkennung mit dem file_path aus dem vorherigen Schritt ein. Bei PDF wird nur das erste Bild analysiert/erkannt.

POST https://detect-image.truthscan.com/detect

Beispielanfrage

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": true
}'

FILE_PATH ist der Pfad aus der Presign-Antwort (z. B. uploads/...). Vollständige URL mit Ihrem Storage-Host wie im Beispiel bauen.

Optionale Parameter

id: Optionale UUID. Fehlt sie, erzeugt der Server eine neue Dokument-ID. Ist sie gesetzt, darf sie noch nicht existieren; sonst Fehler.
generate_preview: true, um eine Vorschau-URL zu erzeugen (Standard: true). false überspringt die Vorschau.
document_type: Dokumenttyp (Standard: Image).
email: E-Mail-Adresse für die Verarbeitung.
generate_analysis_details: false, um die Detailanalyse zu überspringen (Standard: true).
generate_heatmap: Bei false wird die Heatmap-Erzeugung vollständig übersprungen (Standard: true). Heatmaps werden nur für als KI eingestufte Bilder erzeugt, wenn dieser Wert true ist. Echte Bilder erhalten nie eine Heatmap.
generate_heatmap_overlayed: Steuert, wie die Heatmap dargestellt wird, wenn eine Heatmap erzeugt wird (Standard: true). Gilt nur, wenn generate_heatmap true ist und das Bild als KI-generiert eingestuft wurde. Bei true wird die Heatmap auf dem Original überlagert (Standard-Overlay). Bei false liefert der Dienst eine transparente Heatmap: RGBA-Bild mit JET-farbiger Aktivierungskarte und Alpha vom Modell, mit transparentem Hintergrund zum Überlagern in der UI.
generate_heatmap_normalized: Bei false wird bei der Heatmap-Erzeugung der Normalisierungsschritt für die Aktivierungskarte übersprungen (Standard: true). Gilt nur, wenn generate_heatmap true ist und das Bild als KI-generiert eingestuft wurde. Zusammen mit generate_heatmap_overlayed nutzen, um das Erscheinungsbild zu steuern.
model: Modell- oder Routing-Hinweis (Standard: generic). z. B. generic oder instance_id/model. Ungültige instance_id → 400.
user_agent: Optionaler String für Analytics/Support, am Dokument gespeichert.

Validierung der Heatmap-Flags

Ist generate_heatmap false, setzen Sie generate_heatmap_overlayed oder generate_heatmap_normalized nicht explizit auf true. Die API antwortet mit 422 Unprocessable Entity und Meldungen wie "generate_heatmap_overlayed cannot be true when generate_heatmap is false." oder "generate_heatmap_normalized cannot be true when generate_heatmap is false."

Beispielanfrage (Heatmap aktiviert, Standard)

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-dev.nyc3.digitaloceanspaces.com/uploads/example.jpg",
  "generate_heatmap": true,
  "generate_preview": false,
  "generate_analysis_details": false,
  "model": "generic"
}'

Beispielanfrage (Heatmap deaktiviert)

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-dev.nyc3.digitaloceanspaces.com/uploads/example.jpg",
  "generate_heatmap": false,
  "generate_preview": false,
  "generate_analysis_details": false,
  "model": "generic"
}'

Ungültige Anfrage (422)

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-dev.nyc3.digitaloceanspaces.com/uploads/example.jpg",
  "generate_heatmap": false,
  "generate_heatmap_overlayed": true
}'

Beispielantwort

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

Die Antwort enthält eine eindeutige Bild-ID zum Nachverfolgen des Status.

HTTP-Antworten

Status	Body	Wann
200	JSON: id, status (typischerweise "pending")	Job angenommen — das liefert die API bei Erfolg
400	{"error": "..."}	Validierung (keine URL, Datei nicht hochgeladen, Größe/Typ, doppelte id, ungültiges Modell, Heatmap-Flag-Konflikt usw.)
403	{"error": "..."}	Ungültiger Schlüssel / unzureichende Credits
422	{"error": "..."}	Ungültiger Request-Body (z. B. generate_heatmap_overlayed true, wenn generate_heatmap false ist)
500	{"error": "..."}	Serverfehler

Jede 2xx-Antwort, deren JSON id und status enthält, als Erfolg werten — nicht nur HTTP 200. Proxies oder andere HTTP-Stacks können 201 oder 202 für asynchrone Annahme liefern; JSON-Body prüfen.

Erkennungsstatus und Ergebnisse abfragen

Verwenden Sie den Endpunkt /query mit der Bild-ID, um Status und Ergebnisse abzurufen.

Authentifizierung: Der Anfragetext enthält nur id; es wird kein API-Schlüssel mitgesendet. Wer die UUID kennt, kann abfragen — behandeln Sie Dokument-IDs vertraulich, wenn Zugriffe eingeschränkt werden sollen.

HTTP-Antworten

Status	Body	Wann
200	Einzelbild- oder Massen-Ergebnis-JSON	Gefunden
404	Error detail	Unbekannte id
500	Error detail	Serverfehler

POST https://detect-image.truthscan.com/query

Beispielanfrage

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "IMAGE-ID-GOES-HERE"
}'

Beispielantwort

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "metadata": [
            "No Information Detected for Real/AI",
            "Could not find anything from ExifTool and Pillow metadata"
        ],
        "metadata_basic_source": "null",
        "ocr": [
            "OCR did not detect AI",
            0.0
        ],
        "ml_model": [
            "AI Generated",
            90.2371538185235
        ],
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "pending",
        "analysis_results": null,
        "warnings": [
            { "type": "blur_dark", "label": "Blurred" },
            { "type": "watermark", "label": "Gemini", "confidence": 0.95 },
            { "type": "screen_recapture", "label": "screen", "metrics": { "is_screen": false }, "confidence": 99.99 }
        ]
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Beispielantwort (/query, sichere URLs in der Organisation aktiv)

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detect.undetectable.ai/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
        "analysis_results_status": "ready",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detect.undetectable.ai/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}

Beispielantwort, wenn Analyseergebnisse bereit sind

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "ready",
        "analysis_results": {
            "imageTags": ["person", "portrait", "outdoor", "vineyard", "smiling"],
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": ["Uniform noise pattern typical of diffusion models"],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Ergebnisdetails

is_valid: Gibt an, ob die Bilddatei gültig ist (true/false).
detection_step: Stufe: 1 = nur Metadaten; 2 = Metadaten und ocr; 3 = Metadaten, ocr und ml_model.
final_result: Gesamteinschätzung (z. B. „AI Generated“, „Real“, „Digitally Edited“, „AI Edited“).
confidence: Konfidenz der Erkennung.
metadata: Aus Bild-Metadaten mit ExifTool und Pillow extrahiert.
metadata_basic_source: Kann Hinweise auf Aufnahmegerät, KI-Tool oder Bearbeitung liefern.
ocr: Wasserzeichen-Erkennung unter dem historischen Feldnamen ocr. Zwei-Element-Array [Label, Score]; Label z. B. „Gemini“ oder „OCR did not detect AI“; Score 0–100. In warnings zusammengefasst, wenn ein Label vorliegt.
ml_model: Ergebnisse des ML-Modells.
warnings: Optionales Array mit Warnobjekten (blur_dark, watermark, screen_recapture usw.). Kann leer oder fehlen.
preview_url: Vorschau-URL bei generate_preview true. Direkter Storage oder API-Pfad wie https://<api-host>/preview/<document_id>.
heatmap_status: pending, ready oder failed. Wird weggelassen, wenn das Bild nicht KI-generiert ist oder generate_heatmap bei der Einreichung false war. Die Heatmap-Erzeugung ist asynchron und läuft nur für als KI eingestufte Bilder, wenn generate_heatmap true ist.
heatmap_url: Vorhanden, wenn heatmap_status ready ist, das Bild als KI eingestuft wurde und generate_heatmap bei der Einreichung aktiviert war. Das Erscheinungsbild hängt von generate_heatmap_overlayed ab. Kann direkter Storage oder API-Pfad https://<api-host>/heatmap/<document_id> sein (bei sicheren URLs POST /heatmap/{id} mit Schlüssel).
analysis_results_status: pending, ready, skipped, failed oder analyzing. Entfällt oder null, wenn generate_analysis_details false war.
analysis_results: Ausführliche Analyse wenn aktiviert; siehe Erklärung unten.

Erklärung der Analyseergebnisse

Wenn analysis_results bereit ist, enthält es typischerweise: agreement (strong | moderate | weak | disagreement), imageTags (bis zu fünf kurze Tags), confidence (0–100), keyIndicators, detailedReasoning, visualPatterns und recommendations.

Hinweise

Die Heatmap-Erzeugung ist asynchron und läuft nur für als KI eingestufte Bilder, wenn generate_heatmap true ist (Standard). /query pollen, bis heatmap_status ready ist.
Detailanalyse ist asynchron, außer generate_analysis_details=false. analysis_results_status und analysis_results pollen.
Sichere URLs: heatmap_url und preview_url können den API-Host nutzen; Abruf mit POST /heatmap/{id} und POST /preview/{id} mit Schlüssel.
Nach dem Hauptscore erneut /query pollen, um Heatmap und analysis_results abzuholen.

Heatmap und Overlay

Die Datei unter heatmap_url spiegelt generate_heatmap_overlayed und generate_heatmap_normalized Ihrer /detect- (oder /bulk-upload-)Anfrage wider, wenn generate_heatmap true war: Standard-Overlay (true) ist ein normales Bild mit überlagertem Heatmap; false ist typischerweise ein PNG mit Transparenz zum Compositing. Echte Bilder und Anfragen mit generate_heatmap: false lassen heatmap_status und heatmap_url weg.

Beispielantwort (KI-Bild, Heatmap bei Einreichung deaktiviert)

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235
    }
}

Beispielantwort (KI-Bild, Heatmap ausstehend)

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "heatmap_status": "pending",
        "heatmap_url": null
    }
}

Beispiel: result ~90,24 mit final_result AI Generated und detection_step 3 bedeutet vollständige Pipeline (Metadaten, OCR, ML).

Analyseergebnisse (asynchrone Tiefenanalyse)

Ist generate_analysis_details in /detect true, kann die Detailanalyse nach dem Hauptscore fertig werden. /query pollen, bis analysis_results_status ready (oder skipped/failed) ist.

1. Erstergebnis kann vor der Analyse fertig sein

Kernerkennung (result, final_result, confidence) kann fertig sein, während analysis_results_status noch pending ist.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

Vorgehen

Kernfelder sofort nutzen; weiter pollen, wenn analysis_results benötigt wird.

2. Weiter pollen

/query mit derselben id aufrufen, bis analysis_results_status nicht mehr pending ist.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}'

3. Analyse abgeschlossen

Ist analysis_results_status ready, enthält analysis_results agreement, imageTags, confidence, keyIndicators, detailedReasoning, visualPatterns und recommendations.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "imageTags": [
                "person",
                "portrait",
                "outdoor",
                "vineyard",
                "smiling"
            ],
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": [
                "Uniform noise pattern typical of diffusion models"
            ],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Wenn keine Analyse verfügbar ist

Bei skipped, failed oder fehlendem Status oder generate_analysis_details false gilt die Kernerkennung als final.

{
    "status": "done",
    "result": 12.5,
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

Felder der Analyseergebnisse

analysis_results_status: pending | ready | skipped | failed | analyzing
analysis_results.agreement: strong | moderate | weak | disagreement
analysis_results.imageTags: kurze beschreibende Tags
analysis_results.confidence: 0–100
analysis_results.keyIndicators: konkrete Hinweise
analysis_results.detailedReasoning: kurze Begründung
analysis_results.visualPatterns: weiterreichende Muster
analysis_results.recommendations: nächste Schritte

Bulk-Upload (ZIP)

Mehrere Bilder in einem Vorgang per ZIP. Ablauf wie Einzelbild: Presign (ZIP-Name) → PUT ZIP → POST /bulk-upload → /query pollen.

1. Vorsignierte URL (ZIP)

get-presigned-url mit .zip-Dateinamen verwenden (z. B. images.zip).

GET https://detect-image.truthscan.com/get-presigned-url?file_name=images.zip

Beispielanfrage

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=images.zip' \
--header 'apikey: YOUR API KEY GOES HERE'

2. ZIP hochladen

ZIP per PUT auf die vorsignierte URL mit Content-Type: application/zip.

curl -X PUT '<PRESIGNED_URL_FOR_images.zip>' \
  --header 'Content-Type: application/zip' \
  --header 'x-amz-acl: private' \
  --data-binary '@images.zip'

ZIP-Limits

Max. ZIP-Größe: 100 MB
Max. Bilder pro Bulk: 50
Pro Bild: min. 1 KB, max. 10 MB

Unterstützte Formate in der ZIP

JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG

PDFs in der ZIP werden nicht unterstützt und übersprungen.

SVG wird vor der Erkennung nach PNG konvertiert.

3. ZIP zur Bulk-Erkennung einreichen

POST /bulk-upload mit key und url zum hochgeladenen ZIP-Pfad.

Optionale Parameter

generate_preview: true für Vorschau-URLs pro Bild (Standard: false).
generate_analysis_details: true für Detailanalyse (Standard: false).
generate_heatmap: Bei false wird die Heatmap-Erzeugung vollständig übersprungen (Standard: true). Heatmaps werden nur für als KI eingestufte Bilder erzeugt, wenn dieser Wert true ist. Echte Bilder erhalten nie eine Heatmap.
generate_heatmap_overlayed: Gleiches Verhalten wie bei /detect (Overlay vs. transparente RGBA-Heatmap). Gilt nur, wenn generate_heatmap true ist und das Bild als KI-generiert eingestuft wurde.
generate_heatmap_normalized: Gleiches Verhalten wie bei /detect (Standard: true). Gilt nur, wenn generate_heatmap true ist und das Bild als KI-generiert eingestuft wurde.
model: Modell-Domäne: generic oder instance_id/model.

Validierung der Heatmap-Flags

Beispielanfrage

curl -X 'POST' \
  'https://detect-image.truthscan.com/bulk-upload' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": false,
  "generate_analysis_details": false,
  "model": "generic"
}'

Beispielantwort

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending",
    "expected_count": 12
}

Liefert id, Status pending und expected_count (Anzahl zu analysierender Bilder aus der ZIP).

HTTP-Antworten

Status	Body	Wann
200	JSON: id, status, expected_count	Massen-Job angenommen
400	{"error": "..."} (may include skipped)	ZIP-Validierungsfehler
403	{"error": "..."}	Auth / Credits
500	{"error": "..."}	Serverfehler

Gleiche Regel wie /detect: jede 2xx mit id, status und expected_count (falls vorhanden) ist Erfolg.

Aktualisierung der Bulk-ZIP-Ergebnisse

Nach Einreichung: Status pending, dann analyzing.
results listet jedes Bild; pending-Einträge haben result und result_details null bis fertig.
Heatmaps und Analysedetails in result_details können noch pending sein.
Sind alle Bilder fertig, wird der Gesamtstatus done; bei Fehlschlag failed.
/query kann vor Abschluss der ZIP-Verarbeitung Teilergebnisse liefern.

4. Bulk-Ergebnisse abfragen

POST /query mit der id von /bulk-upload. Gleicher Endpunkt wie Einzelbild; Antwortform hängt von Einzel- vs. ZIP-Batch ab.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9"
}'

Beispielantwort (noch in Verarbeitung)

{
  "id": "3b81fb24-dd23-40e7-ae95-82f823f44098",
  "status": "analyzing",
  "results": [
    {
      "id": "4600c7e5-00ec-469d-9117-ff20e0f1c1fa",
      "status": "done",
      "result": 44.0006,
      "result_details": {},
      "filename": "photo1.jpg",
      "preview_url": null
    },
    {
      "id": "2f770c89-352a-4d53-b6a3-a2147ca2c0ae",
      "status": "pending",
      "result": null,
      "result_details": null,
      "filename": "photo2.jpg",
      "preview_url": null
    }
  ],
  "skipped": []
}

Antwortfelder (Bulk-ZIP)

id — ID des Bulk-Vorgangs.
status — pending, dann analyzing, dann done oder failed.
results — Ein Eintrag pro Bild (id, status, result, result_details, filename, preview_url wenn verfügbar).
skipped — Nicht analysierte Dateien (Typ, Größe usw.) mit failed und Grund in result_details.

Abrechnung: Credits nur für erfolgreich analysierte Bilder. Fehlgeschlagene SVG-Konvertierungen und übersprungene Dateien werden nicht berechnet.

Sichere Heatmap- und Vorschau-Assets

Zeigen heatmap_url oder preview_url in /query auf den API-Host (nicht direkt auf Object Storage), Bytes per POST mit Ihrem Schlüssel abrufen.

POST /heatmap/{id}

POST /preview/{id}

JSON-Anfragetext: { "key": "YOUR-API-KEY-GOES-HERE" }

Heatmap-Antworten (HTTP-Status und Content-Type prüfen)

200 + Binär (image/png usw.) — Heatmap verfügbar. X-Heatmap-Status kann gesetzt sein.
202 + JSON — heatmap_status pending; /query pollen und erneut versuchen.
200 + JSON — Keine Heatmap (optional/fehlgeschlagen); kein Serverfehler.
500 + JSON — heatmap_url vorhanden, Download aus Storage fehlgeschlagen; später erneut.
404 + JSON — Dokument-ID nicht gefunden.
403 + JSON — API-Schlüssel gehört nicht zu diesem Dokument.

Vorschau: POST /preview/{id} liefert Rohbytes. 404 mit JSON, wenn keine Vorschau erzeugt wurde (generate_preview false).

Beispiele

curl -X POST 'https://detect-image.truthscan.com/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output heatmap.png

curl -X POST 'https://detect-image.truthscan.com/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output preview.png

Intern: Organisationsnutzung mit Stripe synchronisieren (Job-Geheimnis)

Nur für vertrauenswürdige Backend-Jobs, nicht für normale API-Kunden. Header x-job-secret muss JOB_SECRET des Servers entsprechen. Synchronisiert gemessene TruthScan-Organisationsnutzung mit Stripe für einen Datumsbereich.

POST /organizations/{org_id}/usage/sync-to-stripe

Header: x-job-secret: <JOB_SECRET>

JSON-Body: start_date, end_date, optionale idempotency_id für Stripe-Meter.

Antwort u. a. success, organization_id, total_documents, value_sent_to_stripe, report_date, message. 400 wenn Organisation nicht gemessen oder stripe_customer_id fehlt; 401 bei ungültigem Geheimnis; 404 Organisation nicht gefunden; 500 Stripe/Konfiguration.

Benutzer-Credits prüfen

Dieser Endpunkt akzeptiert den apikey per Header und liefert Credit-Details.

GET https://detect-image.truthscan.com/check-user-credits

Beispielanfrage

curl -X 'GET' \
  'https://detect-image.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

Beispielantwort

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

Bei externen Integrationen ist oft nur das Feld credits gefüllt.

Health Check

Prüft den Zustand des API-Servers.

GET https://detect-image.truthscan.com/health

Beispielanfrage

curl -X 'GET' \
  'https://detect-image.truthscan.com/health' \
  -H 'accept: application/json'

Beispielantwort

{
    "status": "healthy"
}

Antwort „healthy“ bedeutet, dass der Dienst normal läuft.

Fehler

Die meisten Fehler entstehen durch falsche Parameter. Prüfen Sie jeden Aufruf und die Beispiele.

Die verwendeten Fehlercodes entsprechen üblichen REST-Konventionen:

Code	Bedeutung
400	Bad Request — Ungültige Anfrage.
401	Unauthorized — Ungültiges Job-Geheimnis (interne Endpunkte) oder ähnlicher Auth-Fehler.
403	Forbidden — Ungültiger API-Schlüssel, Zugriff verweigert oder unzureichende Credits.
404	Not Found — Ressource nicht gefunden.
405	Method Not Allowed — Ungültige HTTP-Methode für die Ressource.
406	Not Acceptable — Angeforderter Inhalt ist nicht JSON.
410	Gone — Ressource an diesem Endpunkt wurde entfernt.
422	Invalid Request Body — Body fehlerhaft, ungültig oder unvollständig.
429	Too Many Requests — Sie haben das Rate Limit Ihres API-Schlüssels überschritten (siehe Rate Limits). Body: {"error":"Too many requests"}; der Header X-RateLimit-Retry-After zeigt die Wartezeit in Sekunden.
500	Internal Server Error — Serverfehler; bitte später erneut versuchen.
503	Service Unavailable — Wartung oder Überlastung; bitte später erneut.

Häufige Probleme und Lösungen

Authentifizierung

"User verification failed" (403)

Ursache: Ungültiger oder abgelaufener API-Schlüssel

Lösung:

Prüfen Sie, ob der API-Schlüssel korrekt ist
Prüfen Sie im Konto, ob der Schlüssel aktiv ist
Generieren Sie bei Bedarf einen neuen API-Schlüssel

"Not enough credits" (403)

Ursache: Nicht genügend Credits für die Bildverarbeitung

Lösung:

Verbleibende Credits mit /check-user-credits prüfen
Bei Bedarf zusätzliche Credits kaufen

Eingabevalidierung

"Input URL cannot be empty" (400)

Ursache: Leere oder ungültige URL übermittelt

Lösung:

Stellen Sie sicher, dass die URL nicht leer ist
Entfernen Sie führende/nachfolgende Leerzeichen in Dateinamen
Prüfen Sie die URL-Kodierung

"Input email is empty" (400)

Ursache: Fehlende E-Mail für die URL-Verarbeitung

Lösung:

Geben Sie eine gültige E-Mail-Adresse an
Prüfen Sie das E-Mail-Format

"Unsupported image type" (400)

Ursache: Dateiformat wird nicht unterstützt

Lösung:

Konvertieren Sie in ein unterstütztes Format (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF)
Prüfen Sie die Dateiendung

"File size is too small" (400)

Ursache: Bilddatei liegt unter der Mindestgröße

Lösung:

Verwenden Sie eine größere Datei (mindestens 1 KB)
Prüfen Sie, ob die Datei beim Upload beschädigt wurde

"File size exceeds limit" (400)

Ursache: Bilddatei ist zu groß

Lösung:

Komprimieren oder verkleinern Sie das Bild; das Limit in MB steht in der API-Fehlermeldung
Verwenden Sie ein anderes Bildformat

"Invalid file type" (400)

Ursache: Dateityp-Validierung fehlgeschlagen

Lösung:

Stellen Sie sicher, dass es sich um ein gültiges Bildformat handelt
Prüfen Sie, ob die Datei nicht beschädigt ist
MIME-Typ und Dateiendung müssen zusammenpassen

Verarbeitung

Bildstatus „failed"

Ursache: Verarbeitung aus verschiedenen Gründen fehlgeschlagen

Lösung:

Prüfen Sie, ob die URL ein unterstütztes Format hat
Stellen Sie sicher, dass die Bilddatei gültig und nicht beschädigt ist
Einhaltung der Größenanforderungen
Bei anhaltenden Problemen den Support kontaktieren

"User not found"

Ursache: Ungültige Benutzer-ID

Lösung:

Benutzer-ID prüfen
Konto muss aktiv sein
Bei Bedarf erneut authentifizieren

"File metadata could not be fetched" (500)

Ursache: Auf die hochgeladene Datei kann nicht zugegriffen werden

Lösung:

Prüfen Sie, ob der Upload erfolgreich war
Datei-URL muss erreichbar sein
Upload ggf. wiederholen

Upload

"Image upload failed" (403/400)

Ursache: Ungültige oder abgelaufene vorsignierte URL oder Speicherproblem

Lösung:

Vorsignierte URL zeitnah nach Erhalt verwenden
Content-Type muss zum Dateiformat passen
Leerzeichen im Dateinamen vor dem Upload entfernen
Bei Bedarf neue vorsignierte URL anfordern

"Invalid pre-signed URL" (400)

Ursache: Dateiname mit Leerzeichen oder abgelaufene/korrupte vorsignierte URL

Lösung:

Leerzeichen im Dateinamen vor der Presign-Anfrage entfernen
Alphanumerische Zeichen, Bindestriche und Unterstriche verwenden
Bei Bedarf neue vorsignierte URL anfordern

Bulk-Upload

"URL must point to a ZIP file" (400)

Ursache: Die URL für /bulk-upload zeigt nicht auf eine ZIP-Datei

Lösung:

get-presigned-url?file_name=images.zip (oder anderer .zip-Name) verwenden
Gültige ZIP auf die vorsignierte URL hochladen
Sicherstellen, dass bulk-upload dieselbe hochgeladene ZIP-URL verwendet

"ZIP file too large" (400)

Ursache: ZIP überschreitet 100 MB

Lösung:

Bildanzahl reduzieren oder komprimieren
In mehrere Bulk-Uploads aufteilen

"Too many files" (400)

Ursache: ZIP enthält mehr als 50 gültige Bilder

Lösung:

Auf höchstens 50 Bilder pro ZIP begrenzen
Mehrere Bulk-Uploads nutzen

"No valid images found in ZIP" (400)

Ursache: Alle Dateien in der ZIP wurden übersprungen (Format, Größe, Pfad usw.)

Lösung:

Unterstützte Formate (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
PDF ist im Bulk nicht unterstützt
Jedes Bild mindestens 1 KB und höchstens 10 MB
Keine versteckten Dateien (Name beginnt mit .) und keine Pfad-Traversal (..)

"Document is not a bulk upload (image-zip) result" (400)

Ursache: Die id passt nicht zum Upload-Typ (Einzelbild vs. ZIP-Batch)

Lösung:

id von /detect für Einzelbild-Einreichungen verwenden
id von /bulk-upload für ZIP-Einreichungen verwenden

Hilfe benötigt?

Weitere Informationen zur API oder technischer Support — kontaktieren Sie uns.

Kontakt

Häufige Fragen zur API

Antworten auf die häufigsten Fragen zur KI-Bilderkennungs-API.