AI Image Detection API

1. Verkrijg een pre-signed upload-URL

Vraag eerst een pre-signed URL aan bij de API. Met deze URL upload u uw afbeeldingsbestand veilig naar de storage-server.

Voor PDF-bestanden wordt alleen de eerste afbeelding gedetecteerd (single-file flow).

Gebruik een .zip-bestandsnaam op dit endpoint als u een ZIP via bulk upload wilt indienen.

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

Voorbeeldrequest

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

Voorbeeldresponse

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

Het document_id is een nieuwe UUID voor deze upload (correlatie/logging). Het id dat u voor /detect of /bulk-upload gebruikt, wordt toegewezen bij het indienen van die endpoints, tenzij u een optioneel id meegeeft op /detect.

2. Upload de afbeelding

Gebruik de presigned_url om uw afbeelding te uploaden via een PUT-request. Zet Content-Type correct volgens uw bestandsformaat.

Voorbeeldrequest

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'

Extra uploadvoorbeelden (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'

Het bestandsformaat moet tijdens upload consistent blijven. Een geslaagde upload geeft HTTP 200.

3. Dien afbeelding in voor AI detection

Na upload: dien in voor AI detection door te verwijzen naar file_path uit de vorige stap. Bij PDF-uploads wordt alleen de eerste afbeelding geanalyseerd.

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

Voorbeeldrequest

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 is het pad uit de presigned-URL-stap (bijv. uploads/...). Bouw de volledige URL met uw storage host zoals in het voorbeeld.

Voorbeeldresponse

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

De response bevat een unieke image-ID om de detection-status te volgen.

1. Eerste resultaat kan vóór analyse klaar zijn

Kern-detection (result, final_result, confidence) kan klaar zijn terwijl analysis_results_status nog pending is.

{
    "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. Blijf pollen

Roep /query met hetzelfde id aan tot analysis_results_status verandert van pending.

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 voltooid

Als analysis_results_status ready is, bevat analysis_results agreement, imageTags, confidence, keyIndicators, detailedReasoning, visualPatterns en 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/..."
}

Wanneer analyse niet beschikbaar is

Als analysis_results_status skipped, failed of ontbreekt, of generate_analysis_details false was, beschouw kern-detection als definitief.

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

"User verification failed" (403)

Oorzaak: Ongeldige of verlopen API key

Oplossing:

1. Controleer of uw API key correct is
2. Controleer of uw API key actief is in uw account
3. Genereer zo nodig een nieuwe API key

"Not enough credits" (403)

Oorzaak: Onvoldoende credits voor image processing

Oplossing:

1. Controleer resterende credits via /check-user-credits
2. Koop extra credits indien nodig

"Input URL cannot be empty" (400)

Oorzaak: Lege of ongeldige URL

Oplossing:

1. Zorg dat url niet leeg is
2. Verwijder leading/trailing whitespace in namen
3. Controleer URL-encoding

"Input email is empty" (400)

Oorzaak: Ontbrekende e-mail voor URL-verwerking

Oplossing:

1. Geef een geldig e-mailadres bij URL-submits
2. Controleer het e-mailformaat

"Unsupported image type" (400)

Oorzaak: Bestandsformaat niet ondersteund

Oplossing:

1. Converteer naar een ondersteund formaat (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF)
2. Controleer de bestandsextensie

"File size is too small" (400)

Oorzaak: Bestand kleiner dan minimum

Oplossing:

1. Gebruik een groter bestand (minimaal 1KB)
2. Controleer of het bestand tijdens upload corrupt raakte

"File size exceeds limit" (400)

Oorzaak: Bestand te groot

Oplossing:

1. Comprimeer of verklein; maximum staat per deployment (foutmelding vermeldt limiet in MB)
2. Gebruik een ander formaat

"Invalid file type" (400)

Oorzaak: File type validation mislukt

Oplossing:

1. Zorg dat het bestand een geldige image is
2. Controleer of het bestand niet corrupt is
3. MIME type moet bij extensie passen

Image status "failed"

Oorzaak: Verwerking mislukt om diverse redenen

Oplossing:

1. Controleer of de URL een ondersteund formaat heeft
2. Controleer of het bestand geldig en niet corrupt is
3. Controleer de grootte-eisen
4. Neem contact op met support als het aanhoudt

"User not found"

Oorzaak: Ongeldige user ID

Oplossing:

1. Controleer de user ID
2. Controleer of het account actief is
3. Authenticeer opnieuw indien nodig

"File metadata could not be fetched" (500)

Oorzaak: Geen toegang tot geüpload bestand

Oplossing:

1. Controleer of upload geslaagd is
2. Controleer of de file URL bereikbaar is
3. Upload opnieuw

"Image upload failed" (403/400)

Oorzaak: Ongeldige of verlopen pre-signed URL, of problemen met storage

Oplossing:

1. Gebruik de pre-signed URL snel na ontvangst
2. Controleer of Content-Type bij het formaat past
3. Verwijder spaties uit de bestandsnaam vóór upload
4. Genereer zo nodig een nieuwe pre-signed URL

"Invalid pre-signed URL" (400)

Oorzaak: Bestandsnaam met spaties of verlopen/corrupte pre-signed URL

Oplossing:

1. Verwijder spaties vóór het aanvragen van een pre-signed URL
2. Gebruik alfanumeriek, koppeltekens en underscores
3. Genereer zo nodig een nieuwe pre-signed URL

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

Oorzaak: De URL voor /bulk-upload wijst niet naar een ZIP

Oplossing:

1. Gebruik get-presigned-url?file_name=images.zip (of andere .zip-naam)
2. Upload een geldige ZIP naar de presigned URL
3. Zorg dat bulk-upload url naar die ZIP wijst

"ZIP file too large" (400)

Oorzaak: ZIP groter dan maximum (100MB)

Oplossing:

1. Verminder aantal afbeeldingen of comprimeer
2. Splits over meerdere bulk uploads

"Too many files" (400)

Oorzaak: ZIP bevat meer dan 50 geldige afbeeldingen

Oplossing:

1. Maximaal 50 afbeeldingen per ZIP
2. Splits over meerdere bulk uploads

"No valid images found in ZIP" (400)

Oorzaak: Alle bestanden overgeslagen (formaat, grootte, pad, enz.)

Oplossing:

1. Gebruik ondersteunde formaten (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
2. PDF wordt in bulk niet ondersteund
3. Elke afbeelding minimaal 1KB en maximaal 10MB
4. Vermijd hidden files (.) en path traversal (..)

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

Oorzaak: Het id hoort niet bij dit uploadtype (single image vs ZIP-batch)

Oplossing:

1. Gebruik het id van /detect voor single-image
2. Gebruik het id van /bulk-upload voor ZIP