KI-Bilderkennungs-API

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.

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.

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

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,
  "generate_analysis_details": true
}'

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

Beispielantwort

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

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

1. Erstes Ergebnis steht fest (Analyse noch ausstehend)

Wenn Sie mit 'generate_analysis_details': true einreichen und zum ersten Mal mit Status 'done' abfragen, sind die Kernerkennungsergebnisse (result, final_result, confidence) bereit. Allerdings kann analysis_results_status 'pending' sein — das bedeutet, die KI-Tiefenanalyse wird noch im Hintergrund verarbeitet.

{
    "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 abfragen für Analyseergebnisse

Rufen Sie den /query-Endpunkt weiterhin mit derselben Bild-ID auf. Überprüfen Sie das Feld analysis_results_status bei jeder Antwort. Wenn es von 'pending' zu 'done' wechselt, wird das analysis_results-Objekt ausgefüllt.

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 — Vollständige Antwort

Sobald analysis_results_status 'done' ist, enthält das analysis_results-Objekt die vollständige KI-Tiefenanalyse mit Übereinstimmungsniveau, Konfidenz, Schlüsselindikatoren, detaillierter Begründung, visuellen Mustern und Empfehlungen.

{
    "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": {
            "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

Wenn analysis_results_status 'skipped', null oder fehlend ist, wird keine Tiefenanalyse für dieses Bild erstellt. Dies geschieht, wenn 'generate_analysis_details' in der /detect-Anfrage nicht auf 'true' gesetzt wurde, oder bei bestimmten Bildtypen und Erkennungsszenarien. Behandeln Sie die ersten Erkennungsergebnisse als endgültig.

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

"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

"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

"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

"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