API-Dokumentation

KI-Bilderkennungs-API

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

Probieren Sie es ohne Code aus, indem Sie unseren FastAPI-Endpunkt besuchen: https://detect-image.truthscan.com/docs

Authentifizierung

TruthScan verwendet API-Schlüssel, um den Zugriff auf die API zu ermöglichen. Sie können Ihren API-Schlüssel oben auf der Seite in unserem Entwicklerportal abrufen.

TruthScan erwartet, dass der API-Schlüssel in allen API-Anfragen an den Server im Anforderungstext wie folgt enthalten ist:

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

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

KI-Bilderkennung

Erkennen (3-Schritte-Prozess)

Der KI-Bilderkennungsworkflow besteht aus den folgenden Schritten:

  • Eine vorsignierte Upload-URL abrufen
  • Das Bild hochladen
  • Das Bild zur Erkennung einreichen

1. Eine vorsignierte Upload-URL abrufen

Beginnen Sie damit, eine vorsignierte URL von der API anzufordern. Diese URL ermöglicht es Ihnen, Ihre Bilddatei sicher auf den Speicherserver hochzuladen.

Unterstützte Dateiformate

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

Wichtiger Hinweis

Es ist notwendig, Leerzeichen aus dem Bilddateinamen zu entfernen, wenn Sie eine vorsignierte URL anfordern.

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://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
  "file_path": "uploads/example.jpg"
}

2. Das Bild hochladen

Verwenden Sie die bereitgestellte 'presigned_url', um Ihr Bild über eine PUT-Anfrage hochzuladen. Stellen Sie sicher, dass der richtige Inhaltstyp entsprechend Ihrem Bildformat festgelegt ist.

Wichtiger Hinweis

Es ist notwendig, Leerzeichen aus dem Bilddateinamen zu entfernen, wenn Sie das Bild hochladen.

Beispielanfrage

curl -X PUT 'https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...' \
  --header 'Content-Type: image/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg' # Attachment

Dateigrößenbeschränkungen

  • Minimale Dateigröße: 1KB
  • Maximale Dateigröße: 10MB

Stellen Sie sicher, dass das Dateiformat während des Upload-Prozesses konsistent bleibt. Ein erfolgreicher Upload gibt einen Statuscode von 200 zurück.

3. Bild zur KI-Erkennung einreichen

Nach dem Hochladen reichen Sie das Bild zur KI-Erkennung ein, indem Sie auf den 'file_path' aus dem vorherigen Schritt verweisen.

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

Der 'FILE_PATH' bezieht sich auf den Pfad, der aus der Antwort im ersten Schritt 'Eine vorsignierte Upload-URL abrufen' erhalten wurde.

Optionale Parameter

  • generate_preview: Auf 'true' setzen, um eine Vorschau-URL für das Bild zu generieren (Standard: 'false')
  • document_type: Dokumenttyp (Standard: 'Image')
  • email: E-Mail-Adresse für die Verarbeitung

Beispielantwort

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

Die Antwort enthält eine eindeutige Bild-ID zur Verfolgung des Erkennungsstatus.

Abfrage

Dieser Endpunkt akzeptiert eine von der /detect-Anfrage zurückgegebene Bild-ID. Und gibt den Status der Bildeinreichung sowie das vollständige Ergebnis der KI-Erkennungsoperation zurück, einschließlich Metadaten, OCR und ML-Modellanalyse.

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/...."
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Ergebnisinterpretation

  • result: Punktzahl von 1-100, die die Wahrscheinlichkeit angibt, dass das Bild KI-generiert ist. Höhere Punktzahlen = größere KI-Wahrscheinlichkeit.
  • final_result: Die Gesamtbestimmung (z.B. 'AI Generated', 'Real', 'Digitally Edited', 'AI Edited')
  • confidence: Die Vertrauensbewertung der Erkennung
  • detection_step: Gibt die Phase an, in der die Erkennung abgeschlossen wurde. 1 = Nur Metadaten zurückgegeben, 2 = Gibt Metadaten und OCR zurück, 3 = Gibt Metadaten, OCR und ML-Modellergebnisse zurück (am umfassendsten)
  • metadata: Aus Bildmetadaten extrahierte Informationen unter Verwendung von ExifTool und Pillow
  • ocr: Ergebnisse der optischen Zeichenerkennung (OCR) zur Wasserzeichenerkennung
  • ml_model: Ergebnisse des maschinellen Lernmodells (ConvNeXt-basierter Klassifikator)
  • preview_url: URL zum Vorschaubild (wenn generate_preview auf true gesetzt war)
  • heatmap_status: Status der Heatmap-Generierung ('pending' oder 'ready'). Hinweis: Die Heatmap-Generierung ist asynchron. Zunächst ist heatmap_status 'pending' und heatmap_url kann fehlen oder null sein. Wenn fertig, wird heatmap_status zu 'ready' und heatmap_url wird ausgefüllt.
  • heatmap_url: URL zum Heatmap-Bild, verfügbar wenn heatmap_status 'ready' ist. Nur verfügbar für Bilder mit einer Punktzahl >= 20.

Wichtiger Hinweis

Die Heatmap-Generierung ist asynchron. Zunächst ist heatmap_status 'pending' und heatmap_url kann fehlen oder null sein. Wenn fertig, wird heatmap_status zu 'ready' und heatmap_url wird ausgefüllt. Heatmaps werden nur für Bilder mit einer Punktzahl >= 20 generiert.

Hier zeigt "result": 90.24 eine hohe Wahrscheinlichkeit an, dass das Bild KI-generiert wurde. Das "final_result": "AI Generated" liefert eine klare Bestimmung, und "confidence": 90.24 zeigt hohes Vertrauen in dieses Ergebnis. Das Feld "detection_step": 3 zeigt an, dass die vollständige Analyse (Metadaten, OCR und ML-Modell) abgeschlossen wurde. Der "heatmap_status": "ready" und "heatmap_url" bieten Zugriff auf die visuelle Heatmap, die als KI-generiert erkannte Bereiche zeigt.

Benutzerguthaben prüfen

Dieser Endpunkt akzeptiert den API-Schlüssel des Benutzers über den Header. Und gibt die Guthabendetails des Benutzers zurück.

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
}

Gesundheitsprüfung

Dieser Endpunkt ermöglicht es Ihnen, den Status des KI-Bilderkennungsdienstes zu überprüfen.

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

Beispielanfrage

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

Beispielantwort

{
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z"
}

Eine "healthy"-Antwort zeigt an, dass der Dienst normal funktioniert.

Fehler

Die meisten Fehler werden durch falsche Parameter verursacht, die an die API gesendet werden. Überprüfen Sie die Parameter jedes API-Aufrufs doppelt, um sicherzustellen, dass sie richtig formatiert sind, und versuchen Sie, den bereitgestellten Beispielcode auszuführen.

Die generischen Fehlercodes, die wir verwenden, entsprechen dem REST-Standard:

FehlercodeBedeutung
400Bad Request -- Ihre Anfrage ist ungültig.
403Forbidden -- Der API-Schlüssel ist ungültig oder es gibt nicht genügend Guthaben für die Bildverarbeitung.
404Not Found -- Die angegebene Ressource existiert nicht.
405Method Not Allowed -- Sie haben versucht, auf eine Ressource mit einer ungültigen Methode zuzugreifen.
406Not Acceptable -- Sie haben ein Format angefordert, das nicht JSON ist.
410Gone -- Die Ressource an diesem Endpunkt wurde entfernt.
422Invalid Request Body -- Ihr Anforderungstext ist falsch formatiert oder ungültig oder es fehlen Parameter.
429Too Many Requests -- Sie senden zu viele Anfragen! Verlangsamen Sie!
500Internal Server Error -- Wir hatten ein Problem mit unserem Server. Versuchen Sie es später erneut.
503Service Unavailable -- Wir sind vorübergehend wegen Wartungsarbeiten offline. Bitte versuchen Sie es später erneut.

Häufige Probleme und Lösungen

Authentifizierungsprobleme

"Benutzerüberprüfung fehlgeschlagen" (403)

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

Lösung:

  1. Überprüfen Sie, ob Ihr API-Schlüssel korrekt ist
  2. Überprüfen Sie, ob Ihr API-Schlüssel in Ihrem Konto aktiv ist
  3. Versuchen Sie, Ihren API-Schlüssel neu zu generieren

"Nicht genügend Guthaben" (403)

Ursache: Unzureichendes Guthaben für die Bildverarbeitung

Lösung:

  1. Überprüfen Sie Ihr verbleibendes Guthaben mit /check-user-credits
  2. Kaufen Sie bei Bedarf zusätzliches Guthaben
  3. Optimieren Sie die Bildgröße vor dem Hochladen, um weniger Guthaben zu verbrauchen

Eingabevalidierungsprobleme

"Nicht unterstütztes Dateiformat" (400)

Ursache: Nicht unterstütztes oder ungültiges Bildformat eingereicht

Lösung:

  1. Überprüfen Sie, ob das Bildformat unterstützt wird (JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
  2. Stellen Sie sicher, dass die Datei nicht beschädigt ist
  3. Überprüfen Sie den Content-Type-Header beim Hochladen

"Datei zu groß" (400)

Ursache: Dateigröße überschreitet das 10MB-Limit

Lösung:

  1. Verkleinern oder komprimieren Sie das Bild auf unter 10MB
  2. Überprüfen Sie die Dateigröße vor dem Hochladen
  3. Verwenden Sie nach Möglichkeit effizientere Formate wie WebP

Verarbeitungsprobleme

"Anfrage-Timeout" (WebSocket)

Ursache: Die Bildverarbeitung hat zu lange gedauert

Lösung:

  1. Versuchen Sie es mit einem kleineren oder weniger komplexen Bild
  2. Überprüfen Sie, ob der Dienst eine hohe Last erfährt
  3. Wiederholen Sie die Anfrage

Dokumentstatus "fehlgeschlagen"

Ursache: Die Verarbeitung ist aus verschiedenen Gründen fehlgeschlagen

Lösung:

  1. Überprüfen Sie, ob das Bild die Mindestanforderungen erfüllt (1KB - 10MB)
  2. Überprüfen Sie, ob das Bild in einem unterstützten Format vorliegt
  3. Überprüfen Sie, ob der Upload erfolgreich abgeschlossen wurde, bevor Sie zur Erkennung einreichen
  4. Kontaktieren Sie den Support, wenn das Problem weiterhin besteht

Upload-Probleme

"Bild-Upload fehlgeschlagen" (403/400)

Ursache: Ungültige oder abgelaufene vorsignierte URL oder Probleme mit dem Speicherserver

Lösung:

  1. Stellen Sie sicher, dass Sie die vorsignierte URL sofort nach Erhalt verwenden (kann ablaufen)
  2. Überprüfen Sie, ob der Content-Type-Header für das Bildformat korrekt ist
  3. Entfernen Sie Leerzeichen aus dem Dateinamen vor dem Hochladen
  4. Versuchen Sie, eine neue vorsignierte URL zu generieren, wenn die aktuelle abgelaufen ist

"Ungültige vorsignierte URL" (400)

Ursache: Dateiname mit Leerzeichen oder abgelaufene/beschädigte vorsignierte URL

Lösung:

  1. Entfernen Sie alle Leerzeichen aus dem Dateinamen, bevor Sie die vorsignierte URL anfordern
  2. Verwenden Sie nur alphanumerische Zeichen, Bindestriche und Unterstriche im Dateinamen
  3. Generieren Sie bei Bedarf eine neue vorsignierte URL

Brauchen Sie Hilfe?

Für weitere Informationen zur Verwendung unserer API oder für technischen Support kontaktieren Sie uns bitte.

Kontaktieren Sie uns

API Häufig gestellte Fragen

Finden Sie Antworten auf die häufigsten Fragen zu unserer KI-Bilderkennungs-API.