API di rilevamento immagini IA

1. Ottenere un URL di upload pre-firmato

Richiedete all'API un URL pre-firmato. Consente di caricare in modo sicuro il file immagine sul server di storage.

Per i file PDF viene rilevata solo la prima immagine (flusso a file singolo).

Usate un nome file .zip su questo endpoint se intendete inviare uno ZIP tramite bulk upload.

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

Esempio di richiesta

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

Esempio di risposta

{
  "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 è un nuovo UUID generato per questa richiesta di upload (per correlazione/log). L'id usato per /detect o /bulk-upload viene assegnato quando inviate tali endpoint, salvo che passiate un id facoltativo su /detect.

2. Caricare l'immagine

Usate presigned_url per caricare l'immagine con una richiesta PUT. Impostate Content-Type in base al formato dell'immagine.

Esempio di richiesta

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'

Esempi di caricamento aggiuntivi (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'

Mantenete il formato del file coerente durante il caricamento. Un caricamento riuscito restituisce HTTP 200.

3. Inviare l'immagine per il rilevamento IA

Dopo il caricamento, inviate l'immagine per il rilevamento IA facendo riferimento a file_path del passaggio precedente. Per i PDF viene analizzata/rilevata solo la prima immagine.

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

Esempio di richiesta

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 indica il percorso restituito dal passaggio URL pre-firmato (es. uploads/...). Costruite l'URL completo con l'host di storage come nell'esempio.

Esempio di risposta

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

La risposta include un ID immagine univoco per tracciare lo stato del rilevamento.

1. Il risultato iniziale può essere pronto prima dell'analisi

Il rilevamento principale (result, final_result, confidence) può essere disponibile mentre analysis_results_status è ancora pending.

{
    "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. Continuate a interrogare

Chiamate /query con lo stesso id finché analysis_results_status non cambia da 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. Analisi completata

Quando analysis_results_status è ready, analysis_results include agreement, imageTags, confidence, keyIndicators, detailedReasoning, visualPatterns e 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/..."
}

Quando l'analisi non è disponibile

Se analysis_results_status è skipped, failed o assente, o generate_analysis_details era false, considerate definitivo il rilevamento principale.

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

"User verification failed" (403)

Causa: Chiave API non valida o scaduta

Soluzione:

1. Verificate che la chiave API sia corretta
2. Controllate che la chiave sia attiva nell'account
3. Provate a rigenerare la chiave API

"Not enough credits" (403)

Causa: Crediti insufficienti per l'elaborazione

Soluzione:

1. Controllate i crediti residui con /check-user-credits
2. Acquistate crediti aggiuntivi se necessario

"Input URL cannot be empty" (400)

Causa: URL vuoto o non valido

Soluzione:

1. Assicuratevi che url non sia vuoto
2. Rimuovete spazi iniziali/finali nei nomi file
3. Verificate la codifica dell'URL

"Input email is empty" (400)

Causa: Email mancante per l'elaborazione da URL

Soluzione:

1. Fornite un indirizzo email valido quando inviate URL
2. Verificate il formato dell'email

"Unsupported image type" (400)

Causa: Formato file non supportato

Soluzione:

1. Convertite in un formato supportato (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF)
2. Verificate l'estensione del file

"File size is too small" (400)

Causa: File al di sotto della dimensione minima

Soluzione:

1. Usate un file più grande (minimo 1 KB)
2. Verificate che il file non sia corrotto durante il caricamento

"File size exceeds limit" (400)

Causa: File troppo grande

Soluzione:

1. Comprimete o ridimensionate; il limite massimo dipende dal deployment (il messaggio di errore indica il limite in MB)
2. Provate un altro formato

"Invalid file type" (400)

Causa: Validazione del tipo di file fallita

Soluzione:

1. Assicuratevi che sia un formato immagine valido
2. Verificate che il file non sia corrotto
3. MIME type ed estensione devono corrispondere

Stato immagine "failed"

Causa: Elaborazione non riuscita per vari motivi

Soluzione:

1. Verificate che l'URL sia in un formato supportato
2. Controllate che il file sia valido e non corrotto
3. Rispettate i requisiti di dimensione
4. Contattate il supporto se il problema persiste

"User not found"

Causa: ID utente non valido

Soluzione:

1. Verificate l'ID utente
2. Assicuratevi che l'account sia attivo
3. Ripetete l'autenticazione se necessario

"File metadata could not be fetched" (500)

Causa: Impossibile accedere al file caricato

Soluzione:

1. Verificate che il caricamento sia andato a buon fine
2. Controllate che l'URL del file sia raggiungibile
3. Riprovate il caricamento

"Image upload failed" (403/400)

Causa: URL pre-firmato non valido o scaduto, oppure problemi sullo storage

Soluzione:

1. Usate l'URL pre-firmato subito dopo averlo ricevuto
2. Verificate che Content-Type corrisponda al formato
3. Rimuovete gli spazi dal nome file prima del caricamento
4. Generate un nuovo URL pre-firmato se necessario

"Invalid pre-signed URL" (400)

Causa: Nome file con spazi o URL pre-firmato scaduto/non valido

Soluzione:

1. Rimuovete gli spazi dal nome file prima di richiedere l'URL pre-firmato
2. Usate caratteri alfanumerici, trattini e underscore
3. Generate un nuovo URL pre-firmato se necessario

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

Causa: L'URL fornito a /bulk-upload non punta a un file ZIP

Soluzione:

1. Usate get-presigned-url?file_name=images.zip (o altro nome .zip)
2. Caricate uno ZIP valido sull'URL pre-firmato
3. Assicuratevi che url in bulk-upload punti a quello ZIP

"ZIP file too large" (400)

Causa: ZIP oltre la dimensione massima (100 MB)

Soluzione:

1. Riducete il numero di immagini o comprimetele
2. Suddividete in più caricamenti in blocco

"Too many files" (400)

Causa: Lo ZIP contiene più di 50 immagini valide

Soluzione:

1. Portate a 50 o meno immagini per ZIP
2. Suddividete in più caricamenti in blocco

"No valid images found in ZIP" (400)

Causa: Tutti i file nello ZIP sono stati saltati (formato non supportato, troppo piccoli, percorso non valido, ecc.)

Soluzione:

1. Usate formati supportati (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
2. Il PDF non è supportato in blocco
3. Ogni immagine: minimo 1 KB, massimo 10 MB
4. Evitate file nascosti (nomi che iniziano con .) e path traversal (..)

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

Causa: L'id non corrisponde a quel tipo di upload (immagine singola vs batch ZIP)

Soluzione:

1. Usate l'id da /detect per invii a immagine singola
2. Usate l'id da /bulk-upload per invii ZIP