API di Rilevamento Immagini AI

1. Ottieni un URL di Upload Pre-signed

Inizia richiedendo un URL pre-signed dall'API. Questo URL ti permette di caricare in modo sicuro il tuo file immagine sul server di archiviazione.

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

Richiesta di Esempio

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

Risposta di Esempio

{
  "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. Carica l'Immagine

Usa il 'presigned_url' fornito per caricare la tua immagine tramite una richiesta PUT. Assicurati che il tipo di contenuto corretto sia impostato in base al tuo formato immagine.

Richiesta di Esempio

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

Assicurati che il formato del file rimanga coerente durante il processo di upload. Un upload riuscito restituirà un codice di stato 200.

3. Invia Immagine per Rilevamento AI

Dopo il caricamento, invia l'immagine per il rilevamento AI facendo riferimento al 'file_path' dal passaggio precedente.

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

Richiesta di Esempio

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

Il 'FILE_PATH' si riferisce al percorso ottenuto dalla risposta nel passaggio iniziale, 'Ottieni un URL di Upload Pre-signed'.

Risposta di Esempio

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

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

1. Il Risultato Iniziale Si Stabilizza (Analisi Ancora Pending)

Quando invii con 'generate_analysis_details': true e interroghi per la prima volta con stato 'done', i risultati di rilevamento core (result, final_result, confidence) sono pronti. Tuttavia, analysis_results_status potrebbe essere 'pending' — questo significa che l'analisi AI approfondita è ancora in elaborazione in background.

{
    "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. Continua a Interrogare per i Risultati dell'Analisi

Continua a chiamare l'endpoint /query con lo stesso ID immagine. Controlla il campo analysis_results_status in ogni risposta. Quando cambia da 'pending' a 'done', l'oggetto analysis_results sarà popolato.

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 — Risposta Completa

Una volta che analysis_results_status è 'done', l'oggetto analysis_results contiene l'analisi AI approfondita completa con livello di accordo, confidenza, indicatori chiave, ragionamento dettagliato, pattern visivi e raccomandazioni.

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

Quando l'Analisi Non È Disponibile

Se analysis_results_status è 'skipped', null o assente, l'analisi approfondita non sarà prodotta per questa immagine. Questo succede quando 'generate_analysis_details' non era impostato su 'true' nella richiesta /detect, o per certi tipi di immagini e scenari di rilevamento. Dovresti trattare i risultati di rilevamento iniziali come definitivi.

{
    "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. Verifica che la tua chiave API sia corretta
2. Controlla se la tua chiave API è attiva nel tuo account
3. Prova a rigenerare la tua chiave API

"Not enough credits" (403)

Causa: Crediti insufficienti per l'elaborazione immagini

Soluzione:

1. Controlla i tuoi crediti rimanenti usando /check-user-credits
2. Acquista crediti aggiuntivi se necessario
3. Ottimizza la dimensione dell'immagine prima dell'upload per consumare meno crediti

"Unsupported file format" (400)

Causa: Formato immagine non supportato o invalido inviato

Soluzione:

1. Verifica che il formato immagine sia supportato (JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
2. Assicurati che il file non sia corrotto
3. Controlla che l'header Content-Type sia corretto quando carichi

"File too large" (400)

Causa: La dimensione del file supera il limite di 10MB

Soluzione:

1. Ridimensiona o comprimi l'immagine a meno di 10MB
2. Controlla la dimensione del file prima di caricare
3. Usa formati più efficienti come WebP quando possibile

"Request timeout" (WebSocket)

Causa: L'elaborazione dell'immagine ha richiesto troppo tempo

Soluzione:

1. Prova con un'immagine più piccola o meno complessa
2. Controlla se il servizio sta sperimentando alto carico
3. Riprova la richiesta

Stato Documento "failed"

Causa: Elaborazione fallita per vari motivi

Soluzione:

1. Controlla se l'immagine soddisfa i requisiti minimi (1KB - 10MB)
2. Verifica che l'immagine sia in un formato supportato
3. Verifica che l'upload sia completato con successo prima di inviare per il rilevamento
4. Contatta il supporto se il problema persiste

"Image upload failed" (403/400)

Causa: URL pre-signed non valido o scaduto, o problemi con il server di archiviazione

Soluzione:

1. Assicurati di usare l'URL pre-signed immediatamente dopo averlo ricevuto (può scadere)
2. Verifica che l'header Content-Type sia corretto per il formato immagine
3. Rimuovi gli spazi dal nome del file prima di caricare
4. Prova a generare un nuovo URL pre-signed se quello corrente è scaduto

"Invalid pre-signed URL" (400)

Causa: Nome file con spazi o URL pre-signed scaduto/corrotto

Soluzione:

1. Rimuovi tutti gli spazi dal nome del file prima di richiedere l'URL pre-signed
2. Usa solo caratteri alfanumerici, trattini e underscore nel nome del file
3. Genera un nuovo URL pre-signed se necessario