> ## Documentation Index
> Fetch the complete documentation index at: https://docs.identifai.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Classifica un'immagine

> Come avviare la classificazione di un'immagine

Puoi classificare un'immagine a partire da un **file** o da un **URL**.
\
&#x20;Questa sezione spiega come effettuare la richiesta con un file. Con un URL il procedimento è simile: la differenza principale è l'[endpoint](https://docs.identifai.net/it/api-reference/classification/submit-image-from-url.md) da chiamare al *passo 1*.

## Linee guida per l'invio

Data la grande variabilità delle immagini, ti consigliamo di seguire queste semplici linee guida:

* Invia al sistema l'immagine più "vicina" alla fonte: ad esempio, non inviare screenshot o foto di schermi.
* I modelli di analisi delle immagini al momento non sono addestrati a riconoscere le foto di documenti: il risultato, se invii immagini di questo tipo, non è quindi affidabile.
* Per le immagini prese dai social, i risultati più accurati si ottengono inviando immagini senza testi sovrapposti né le modifiche tipiche della condivisione sui social.
* Se l'immagine è disponibile da altre fonti, evita di inviare link ai social, a causa della post-elaborazione applicata dalle varie piattaforme.

## Invia un'immagine tramite l'API

Per classificare un'immagine, effettua una richiesta **POST** a `/api/classification` con i parametri richiesti (per i dettagli sui parametri consulta la sezione [Riferimento API](https://docs.identifai.net/it/api-reference/classification/submit-an-image-for-classification.md)).

```bash theme={null}
curl --request POST \
  --url https://backend.identifai.net/api/classification \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-Api-Key: <api-key>' \
  --header 'Accept: application/json' \
  --form "image=@/path/to/sample.jpg" \
  --form with_morphing=false\
  --form with_tampering=false
```

In risposta riceverai l'identificativo dell'immagine classificata.

> [!TIP]
>
> Puoi anche [classificare un'immagine da URL](https://docs.identifai.net/it/api-reference/classification/submit-image-from-url.md)!

### Recupera i risultati

Usa l'identificativo ricevuto per recuperare i risultati della classificazione con una richiesta **GET** a `/api/classification/{identifier}` (per i dettagli su come strutturare la richiesta consulta la sezione [Riferimento API](https://docs.identifai.net/it/api-reference/classification/get-classification-result.md)).

```bash theme={null}
curl --request GET \
  --url https://backend.identifai.net/api/classification/{identifier} \
  --header 'X-Api-Key: <api-key>'
```

La risposta contiene i risultati della classificazione dell'immagine in formato JSON. Nella risposta trovi un array results, con i risultati della classificazione di ogni modello usato, e un array verdicts, con i risultati di ogni euristica applicata.

> [!NOTE]
>
> La classificazione potrebbe non essere ancora terminata! Se non è ancora completa, continua a inviare la richiesta GET finché il risultato non è disponibile.

## Heatmap

La funzionalità di heatmap (fornita dal modello Ardē) aiuta ad analizzare i
dettagli dell'immagine. Un'immagine inviata senza heatmap potrebbe essere
rilevata come umana, mentre l'analisi della stessa immagine con la heatmap
potrebbe evidenziare tratti artificiali. Questo dipende da come i modelli
interpretano le immagini ricevute in input.

Se la heatmap è disponibile per il tuo utente, puoi richiedere l'analisi con heatmap passando l'argomento `with_heatmap=true`

```bash theme={null}
curl --request POST \
  --url https://backend.identifai.net/api/classification \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-Api-Key: <api-key>' \
  --header 'Accept: application/json' \
  --form "image=@/path/to/sample.jpg" \
  --form with_heatmap=true \
  --form with_morphing=false \
  --form with_tampering=false
```

Il calcolo della heatmap richiede un po' di tempo. Al termine, il risultato includerà anche un modello chiamato `Ardē`:

```json theme={null}
{
  "results": {
      "model": "Ardē",
      "unknown": false,
      "elapsed_time": 5.606042385101318,
      "classification": [
        {
          "label": "human",
          "score": 0.8
        },
        {
          "label": "artificial",
          "score": 0.2
        }
      ]
    }
}
```

Il valore `score` rappresenta l'area totale umana o artificiale. Nell'esempio,
il risultato indica che il 20% dell'immagine è stato classificato come artificiale.

Puoi anche scaricare la heatmap come immagine colorata usando l'apposito [endpoint](https://docs.identifai.net/it/api-reference/classification/get-classification-heatmap.md).

## Smart Full Analysis

La Smart Full Analysis è una modalità di analisi avanzata pensata per ottenere il massimo dal processo di classificazione delle immagini.

Un algoritmo di scoring proprietario individua e seleziona automaticamente le aree dell'immagine con il maggior contenuto informativo, in modo che l'analisi si concentri sui dettagli più rilevanti. L'approccio funziona come una mappa di rilevamento ottimizzata:

1. l'immagine viene suddivisa in una selezione mirata di ritagli ad alto valore;
2. ogni ritaglio viene analizzato e classificato dal modello più avanzato disponibile della famiglia **Revelio**;
3. i risultati dei singoli ritagli vengono combinati in un verdetto complessivo, che tiene conto delle informazioni raccolte dalle diverse aree dell'immagine.

Il risultato è un'analisi più selettiva, efficiente e approfondita, che sfrutta al meglio i modelli Revelio.

> [!NOTE]
>
> La Smart Full Analysis è una versione avanzata e intelligente sia dell'analisi completa standard sia della [heatmap](#heatmap): quando è abilitata, **le sostituisce entrambe**.

> [!WARNING]
>
> `with_smart_analysis` e `with_heatmap` non possono essere combinati: una richiesta con entrambi impostati a `true` viene rifiutata con un errore `422`.

Se la Smart Full Analysis è inclusa nel tuo piano tariffario, puoi abilitarla passando l'argomento `with_smart_analysis=true`:

```bash theme={null}
curl --request POST \
  --url https://backend.identifai.net/api/classification \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-Api-Key: <api-key>' \
  --header 'Accept: application/json' \
  --form "image=@/path/to/sample.jpg" \
  --form with_smart_analysis=true
```

> [!NOTE]
>
> Se la Smart Full Analysis non è inclusa nel tuo piano tariffario, il parametro `with_smart_analysis` viene ignorato e l'immagine viene analizzata con lo scope standard.

## XAI (eXplainable AI)

**Non solo un verdetto. Scopri cosa ha osservato l'intelligenza artificiale per arrivare alla sua decisione.**

Perché Revelio ha classificato un'immagine o un video come generato dall'AI? Quali elementi del contenuto hanno attirato di più la sua attenzione?

Con la nuova funzionalità **XAI – eXplainable AI**, identifAI fa un ulteriore passo verso una maggiore trasparenza e interpretabilità dei suoi modelli di classificazione.

La XAI è un nuovo scope di analisi che arricchisce i verdetti di Revelio con un insieme di strumenti visivi e descrittivi, pensati per aiutarti a capire dove il modello ha concentrato la sua attenzione durante l'analisi.

### Dalla classificazione alla comprensione

Quando la XAI è abilitata, i modelli Revelio non si limitano a restituire un verdetto: generano anche informazioni sui punti di attenzione che hanno caratterizzato il processo di classificazione.

Queste informazioni vengono trasformate in tre strumenti complementari:

> [card] Attention Map
>
> **Guarda dove si concentra l'attenzione.** Una rappresentazione visiva sovrapposta al contenuto originale, che evidenzia le aree su cui il modello si è concentrato di più. Un modo immediato e intuitivo per esplorare ciò che Revelio ha osservato.

> [card] Attention Graph
>
> **Esplora l'analisi più a fondo.** Un grafico che mostra l'andamento e i picchi dell'attenzione del modello, offrendo una prospettiva più tecnica e dettagliata a chi vuole approfondire il comportamento dell'algoritmo.

> [card] Spiegazione AI
>
> **Dalle immagini alle parole.** Una descrizione in linguaggio naturale delle regioni che hanno ricevuto più attenzione, disponibile in più lingue, per rendere le informazioni prodotte dal modello ancora più accessibili e facili da interpretare.

### Più trasparenza, più strumenti per interpretare i risultati

Con la XAI, identifAI fornisce nuove informazioni a supporto dell'interpretazione dei risultati, affiancando alla classificazione tradizionale una prospettiva visiva, analitica e descrittiva.

Un passo avanti verso un'intelligenza artificiale sempre più trasparente, comprensibile e accessibile.

### Disponibile sulla piattaforma web e via API

La XAI è attualmente disponibile per l'analisi di immagini e [video](https://docs.identifai.net/it/classification/classify-video.md#xai-explainable-ai), sia tramite la piattaforma web di identifAI sia via API, così da poter essere integrata facilmente nei tuoi flussi di lavoro esistenti.

> [!NOTE]
>
> **E l'audio?** Ci stiamo lavorando! Il nostro obiettivo è estendere presto queste funzionalità anche all'analisi dei contenuti audio.

> [!WARNING]
>
> **Avviso sul trasferimento dei dati:** abilitando questa funzionalità, i dati delle tue immagini vengono trasferiti alla nostra infrastruttura cloud nell'UE per l'inferenza dei modelli.
>
> Le spiegazioni AI sono generate con modelli non sviluppati da identifAI.

### Abilita la XAI tramite API

La XAI è controllata dai seguenti parametri dell'[API per la classificazione delle immagini](https://docs.identifai.net/it/api-reference/classification/submit-an-image-for-classification.md) e dell'[API per la classificazione delle immagini da URL](https://docs.identifai.net/it/api-reference/classification/submit-image-from-url.md):

| Parametro | Descrizione |
| - | - |
| `with_xai` | Impostalo a `true` per abilitare lo scope XAI. |
| `with_llm_xai` | Impostalo a `true`, insieme a `with_xai`, per ottenere anche le **spiegazioni AI**. Viene ignorato se `with_xai` non è abilitato. |
| `llm_xai_language` | Lingua delle spiegazioni AI: `english`, `italian`, `spanish` o `german` (senza distinzione tra maiuscole e minuscole). Se omesso, viene usata la lingua predefinita del tuo piano tariffario. |

Se la XAI è inclusa nel tuo piano tariffario, puoi abilitarla, insieme alle spiegazioni AI in italiano, in questo modo:

```bash theme={null}
curl --request POST \
  --url https://backend.identifai.net/api/classification \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-Api-Key: <api-key>' \
  --header 'Accept: application/json' \
  --form "image=@/path/to/sample.jpg" \
  --form with_xai=true \
  --form with_llm_xai=true \
  --form llm_xai_language=italian
```

> [!NOTE]
>
> Se la XAI non è inclusa nel tuo piano tariffario, il parametro `with_xai` viene ignorato e l'immagine viene analizzata senza XAI.

> [!WARNING]
>
> Anche le spiegazioni AI devono essere abilitate nel tuo piano tariffario: se il tuo piano include la XAI ma non le spiegazioni AI, una richiesta con `with_llm_xai=true` viene rifiutata con un errore `403`. Un valore di `llm_xai_language` non supportato viene rifiutato con un errore `400`. In entrambi i casi la richiesta viene rifiutata prima di analizzare l'immagine e non vengono consumati crediti.

### Mappe XAI e spiegazioni nei risultati

Quando la XAI è abilitata, ogni risultato per modello in `results` che ha prodotto almeno una mappa XAI contiene un array `explanations`, che elenca **ogni mappa** del modello con la sua spiegazione AI:

```json theme={null}
{
  "status": "done",
  "deferred_status": "done",
  "results": [
    {
      "model": "Revelio",
      "unknown": false,
      "elapsed_time": 1.234,
      "classification": [
        { "label": "human", "score": 0.03 },
        { "label": "artificial", "score": 0.97 }
      ],
      "explanations": [
        {
          "type": "attention_map",
          "method": "legrad",
          "description": "The model focuses on the skin texture around the eyes and on the hairline, where the generated details are less consistent."
        },
        {
          "type": "attention_graph",
          "method": "legrad",
          "description": null
        }
      ]
    }
  ]
}
```

| Campo | Descrizione |
| - | - |
| `type` | La mappa XAI: `attention_map`, `attention_graph` o `heatmap` |
| `method` | Il metodo XAI usato per calcolare la mappa (`legrad`, `transformer_attribution` o `attention_rollout`); `null` per `heatmap` |
| `description` | Descrizione in linguaggio naturale delle regioni che hanno ricevuto più attenzione, nella lingua richiesta con `llm_xai_language`, oppure `null` se non è disponibile (vedi sotto) |

Le spiegazioni AI sono [risultati differiti](https://docs.identifai.net/it/api-reference/deferred-results.md): vengono prodotte dopo l'analisi principale, senza ritardarla. Il verdetto, i risultati della classificazione e l'elenco delle mappe XAI sono disponibili non appena lo `status` dell'invio diventa `done`, mentre le descrizioni vengono compilate in seguito: segui il campo `deferred_status` del [risultato della classificazione](https://docs.identifai.net/it/api-reference/classification/get-classification-result.md), oppure imposta `deferred_webhook_url` per ricevere una notifica quando sono complete.

`description` è `null` quando:

* le spiegazioni AI non sono state richieste (`with_llm_xai` non impostato): le mappe vengono comunque elencate, così puoi [scaricarle](#scarica-attention-map-e-attention-graph);
* la spiegazione non è ancora disponibile, perché i risultati differiti sono ancora in corso;
* la spiegazione è stata richiesta ma non è stato possibile generarla. Se succede a causa di un errore tecnico, `deferred_status` è `errored`, mentre le spiegazioni generate per le altre mappe vengono comunque restituite: vedi [Risultati differiti](https://docs.identifai.net/it/api-reference/deferred-results.md). I crediti delle spiegazioni AI che non è possibile generare vengono rimborsati.

Tieni presente che:

* le spiegazioni sono restituite solo dall'endpoint del [singolo risultato della classificazione](https://docs.identifai.net/it/api-reference/classification/get-classification-result.md): non sono incluse negli elenchi delle classificazioni né nel payload inviato a `webhook_url`. La notifica inviata a `deferred_webhook_url` contiene le descrizioni nei campi `xai` e `heatmaps`;
* i `results` per modello, e quindi le spiegazioni, sono restituiti solo se il tuo piano tariffario espone i dettagli dei modelli;
* quando viene richiesta la [heatmap](#heatmap), questa è elencata con `type` `heatmap` (e `method` `null`) nel risultato del modello `Ardē`; quando è abilitata la [Smart Full Analysis](#smart-full-analysis), la sua heatmap è elencata nei risultati dei modelli che l'hanno prodotta.

### Scarica Attention Map e Attention Graph

L'Attention Map e l'Attention Graph possono essere scaricati come immagini con l'[endpoint per scaricare le mappe XAI](https://docs.identifai.net/it/api-reference/classification/get-classification-xai.md), indicando il `model` che ha prodotto la mappa (come riportato nel campo `model` dei risultati per modello), il `method` XAI (`legrad`, `transformer_attribution` o `attention_rollout`) e il `type` di mappa (`attention_map`, il valore predefinito, o `attention_graph`):

```bash theme={null}
curl --request GET \
  --url 'https://backend.identifai.net/api/classification/xai/{identifier}?model=Revelio&method=legrad&type=attention_map' \
  --header 'X-Api-Key: <api-key>' \
  --output attention_map.png
```

Le mappe prodotte dipendono dal modello: le `explanations` di ogni risultato per modello elencano il `type` e il `method` di ogni mappa disponibile, anche quando le spiegazioni AI non sono state richieste. Se non è disponibile nessuna mappa del modello, metodo e tipo richiesti, l'endpoint restituisce un errore `404`.

> [!TIP]
>
> Quando la XAI è combinata con la [Smart Full Analysis](#smart-full-analysis), la sua heatmap può essere scaricata come di consueto con l'[endpoint per scaricare la heatmap](https://docs.identifai.net/it/api-reference/classification/get-classification-heatmap.md).

## Linee guida per interpretare i risultati

Per interpretare il risultato, ti consigliamo di concentrarti su:

* Revelio come risultato principale per il verdetto (la scelta predefinita della piattaforma), con un'affidabilità maggiore se sono presenti volti e persone.
* Aide per un'analisi dettagliata con il supporto della funzionalità di heatmap.
* Morphing, da considerare solo in presenza di volti.
* Ellen, se l'immagine proviene da fonti in cui in passato è stato accertato l'uso di strumenti di fotoritocco.
* V01 e Brokenwand solo per immagini molto vecchie (e quindi potenzialmente generate con sistemi oggi non più in uso).

Inoltre, per l'analisi con heatmap ti consigliamo di:

* Fare molta attenzione alle dimensioni delle immagini inviate: l'analisi con
  heatmap è particolarmente onerosa dal punto di vista computazionale e il tempo
  di elaborazione aumenta sensibilmente con le dimensioni dell'immagine. Le linee
  guida consigliano di inviare immagini con una risoluzione inferiore a 2k (o 4 megapixel).

## Vedi anche

> [card] [Classifica un video](https://docs.identifai.net/it/classification/classify-video.md)
>
> Scopri come avviare la classificazione di un video e capire se è autentico o generato artificialmente

> [card] [Classifica un audio vocale](https://docs.identifai.net/it/classification/classify-speech.md)
>
> Scopri come avviare la classificazione di un audio vocale e capire se è autentico o generato artificialmente


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.