API zur KI-Bilderkennung

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.

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.

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.

2. Bild hochladen

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

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'

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

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.

Beispielantwort

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

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

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

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

"User verification failed" (403)

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

Lösung:

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

"Not enough credits" (403)

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

Lösung:

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

"Input URL cannot be empty" (400)

Ursache: Leere oder ungültige URL übermittelt

Lösung:

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

"Input email is empty" (400)

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

Lösung:

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

"Unsupported image type" (400)

Ursache: Dateiformat wird nicht unterstützt

Lösung:

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

"File size is too small" (400)

Ursache: Bilddatei liegt unter der Mindestgröße

Lösung:

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

"File size exceeds limit" (400)

Ursache: Bilddatei ist zu groß

Lösung:

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

"Invalid file type" (400)

Ursache: Dateityp-Validierung fehlgeschlagen

Lösung:

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

Bildstatus „failed"

Ursache: Verarbeitung aus verschiedenen Gründen fehlgeschlagen

Lösung:

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

"User not found"

Ursache: Ungültige Benutzer-ID

Lösung:

1. Benutzer-ID prüfen
2. Konto muss aktiv sein
3. Bei Bedarf erneut authentifizieren

"File metadata could not be fetched" (500)

Ursache: Auf die hochgeladene Datei kann nicht zugegriffen werden

Lösung:

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

"Image upload failed" (403/400)

Ursache: Ungültige oder abgelaufene vorsignierte URL oder Speicherproblem

Lösung:

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

"Invalid pre-signed URL" (400)

Ursache: Dateiname mit Leerzeichen oder abgelaufene/korrupte vorsignierte URL

Lösung:

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

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

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

Lösung:

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

"ZIP file too large" (400)

Ursache: ZIP überschreitet 100 MB

Lösung:

1. Bildanzahl reduzieren oder komprimieren
2. In mehrere Bulk-Uploads aufteilen

"Too many files" (400)

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

Lösung:

1. Auf höchstens 50 Bilder pro ZIP begrenzen
2. 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:

1. Unterstützte Formate (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
2. PDF ist im Bulk nicht unterstützt
3. Jedes Bild mindestens 1 KB und höchstens 10 MB
4. 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:

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