> ## 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 video

> Come avviare la classificazione di un video

Puoi classificare un video 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-video-from-url.md) da chiamare al *passo 1*.

## Linee guida per l'invio

L'analisi di un video prevede l'elaborazione del video per estrarne frame specifici. Per questo le linee guida da seguire sono simili a quelle per le immagini:

* Invia al sistema il video più "vicino" alla fonte: ad esempio, non inviare il video di una foto per analizzare la foto, né un video ripreso da un altro video.
* Per i video presi dai social, i risultati più accurati si ottengono inviando video senza testi sovrapposti né le modifiche tipiche della condivisione sui social.
* Se il video è disponibile da altre fonti, evita di inviare link ai social, a causa della post-elaborazione applicata dalle varie piattaforme.

Al momento dell'invio puoi escludere i modelli di morphing. Ti sconsigliamo di attivare il modello di morphing in assenza di volti, per evitare il rischio di falsi positivi.

## Scelta della strategia di estrazione dei frame

Solo per i video è necessario scegliere una strategia di estrazione dei frame, che verranno poi analizzati dai modelli di rilevamento.

Di seguito sono descritte le strategie di estrazione dei frame:

### A intervalli regolari

Con questa modalità vengono estratti N frame (in base al "Numero massimo di frame" scelto), equamente distribuiti lungo la durata del video.

Per attivarla devi aggiungere i seguenti parametri:

```
frames=(5|10|30)
key_frames=false
```

`frames` indica il numero minimo di frame da estrarre. Puoi scegliere tra 5, 10 e 30. Un numero maggiore di frame analizzati corrisponde a un numero maggiore di crediti usati per l'analisi.

### Keyframe

* Keyframe - Default: con questa modalità vengono estratti fino a N iframe. Questi frame rappresentano cambi di scena improvvisi nel video e sono quindi potenzialmente interessanti per analizzare scene diverse.
* Keyframe - Color: con questa modalità vengono estratti fino a N frame che rappresentano il frame "medio" di una scena, calcolato in base ai colori dell'immagine.
* Keyframe - Flow: con questa modalità vengono estratti fino a N frame che rappresentano il frame "più statico" di una scena, calcolato rispetto al frame precedente della scena.

```
frames=(5|10|30)
key_frames=true
key_frames_method=(iframe|color|flow)
```

`frames` indica il numero minimo di frame da estrarre. Puoi scegliere tra 5, 10 e 30. Un numero maggiore di frame analizzati corrisponde a un numero maggiore di crediti usati per l'analisi.

### Volti

Con questa modalità il sistema cerca i frame che contengono almeno un volto: partendo dal campionamento a intervalli regolari, cerca nel video i frame con volti fino a raggiungere il numero di frame da analizzare. È la strategia consigliata per rilevare face swap e morphing, insieme a `with_morphing=true`.

```
frames=(5|10|30)
ensure_face_per_frame=true
with_morphing=true
```

* È un'alternativa ai keyframe: con `ensure_face_per_frame=true`, `key_frames` e `key_frames_method` vengono ignorati.
* La ricerca ha un limite di tempo: nei video in cui i volti sono rari o assenti potrebbero essere analizzati meno frame. I frame non analizzati vengono rimborsati al termine dell'analisi.
* La ricerca può aumentare il tempo di elaborazione e, a seconda del tuo piano tariffario, il costo di ogni frame.

> [!NOTE]
>
> L'estrazione dei volti è una funzionalità del piano tariffario: se il tuo piano non la include, `ensure_face_per_frame` viene ignorato e il video viene analizzato con le altre strategie.

### Momenti specifici

Se sai già quali momenti del video sono rilevanti (ad es. i secondi in cui compare un volto o inizia una scena sospetta), puoi chiedere al sistema di analizzare esattamente quei momenti: viene estratto un frame per ogni timecode indicato.

```
frames_timestamps=00:00:05.000,00:00:12.500,00:01:03.250
```

* I timecode sono separati da virgole e nel formato `HH:MM:SS.mmm` (ore, minuti, secondi e millisecondi), misurati dall'inizio del video. I duplicati vengono contati una sola volta.
* Quando è presente `frames_timestamps`, ha la precedenza sulle altre strategie: `frames`, `key_frames`, `key_frames_method` e `ensure_face_per_frame` vengono ignorati.
* **Viene addebitato un frame per ogni timecode distinto.** Puoi indicare fino a 30 timecode se il tuo piano tariffario ti permette di scegliere il numero di frame, altrimenti fino al numero di frame predefinito (10).
* I timecode oltre la fine del video vengono saltati; se nessuno cade all'interno del video, la classificazione termina con un errore.

Lo stesso vale per la traccia audio del video, analizzata con `with_audio=true`: con `audio_timestamps` il sistema analizza un breve segmento audio centrato su ogni timecode indicato, invece di segmenti distribuiti su tutta la traccia. I timecode abbastanza vicini da cadere nello stesso segmento vengono analizzati insieme, e viene addebitato un segmento audio per ogni timecode distinto (i segmenti non prodotti vengono rimborsati al termine dell'analisi). Puoi indicare fino a 30 timecode audio se il tuo piano tariffario ti permette di scegliere il numero di segmenti audio, altrimenti fino a 5.

```
with_audio=true
audio_timestamps=00:00:05.000,00:00:40.000
```

> [!NOTE]
>
> I momenti specifici sono una funzionalità del piano tariffario, attivata separatamente per i frame e per l'audio: se il tuo piano non li include, `frames_timestamps` e `audio_timestamps` vengono ignorati. I timecode non validi o in numero superiore al consentito vengono rifiutati con un errore `400`.

## Invia un video tramite l'API

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

```bash theme={null}
curl --request POST \
  --url https://backend.identifai.net/api/classification_video \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-Api-Key: <api-key>' \
  --form "video=@/path/to/sample.mp4" \
  --form frames=5 \
  --form with_morphing=false\
  --form with_tampering=false
```

Nella risposta riceverai l'identificativo del video classificato.

Per analizzare invece momenti specifici del video e della sua traccia audio:

```bash theme={null}
curl --request POST \
  --url https://backend.identifai.net/api/classification_video \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-Api-Key: <api-key>' \
  --form "video=@/path/to/sample.mp4" \
  --form frames_timestamps=00:00:05.000,00:00:12.500 \
  --form with_audio=true \
  --form audio_timestamps=00:00:05.000
```

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

### Recupera i risultati

Usa l'identificativo ricevuto per recuperare i risultati della classificazione con una richiesta **GET** a `/api/classification_video/{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-video.md)).

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

La risposta contiene i risultati della classificazione del video in formato JSON. Per la classificazione, il video viene suddiviso in frame. Nella risposta trovi un array results, con l'esito della classificazione di ogni modello applicato a ogni frame analizzato, e un array verdicts, con i risultati di ogni euristica usata.

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

## Smart Full Analysis

La [Smart Full Analysis](https://docs.identifai.net/it/classification/classify-image.md#smart-full-analysis) è disponibile anche per i video: ogni frame analizzato viene suddiviso in una selezione mirata di ritagli ad alto valore, scelti da un algoritmo di scoring proprietario, che vengono classificati dal modello più avanzato della famiglia **Revelio** e combinati nel verdetto del frame.

> [!NOTE]
>
> Come per le immagini, la Smart Full Analysis è una versione avanzata e intelligente dell'analisi completa standard e della heatmap: quando è abilitata, **le sostituisce** per ogni frame analizzato.

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_video \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-Api-Key: <api-key>' \
  --form "video=@/path/to/sample.mp4" \
  --form frames=5 \
  --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 il video viene analizzato con lo scope standard.

## XAI (eXplainable AI)

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

La [XAI – eXplainable AI](https://docs.identifai.net/it/classification/classify-image.md#xai-explainable-ai) è disponibile anche per i video: quando è abilitata, viene applicata a **ogni frame analizzato**. Per ogni frame, i modelli Revelio non si limitano a restituire un verdetto, ma anche le informazioni sui punti di attenzione che hanno caratterizzato la classificazione, trasformate in tre strumenti complementari:

* **Attention Map**: una rappresentazione visiva sovrapposta al frame, che evidenzia le aree su cui il modello si è concentrato di più;
* **Attention Graph**: un grafico che mostra l'andamento e i picchi dell'attenzione del modello;
* **Spiegazione AI**: una descrizione in linguaggio naturale delle regioni che hanno ricevuto più attenzione, disponibile in più lingue.

> [!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 dagli stessi parametri usati per le immagini, disponibili nell'[API per la classificazione dei video](https://docs.identifai.net/it/api-reference/classification/submit-a-video-for-classification.md) e nell'[API per la classificazione dei video da URL](https://docs.identifai.net/it/api-reference/classification/submit-video-from-url.md):

| Parametro | Descrizione |
| - | - |
| `with_xai` | Impostalo a `true` per abilitare lo scope XAI su ogni frame analizzato. |
| `with_llm_xai` | Impostalo a `true`, insieme a `with_xai`, per ottenere anche le **spiegazioni AI** di ogni frame analizzato. 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 in questo modo:

```bash theme={null}
curl --request POST \
  --url https://backend.identifai.net/api/classification_video \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-Api-Key: <api-key>' \
  --form "video=@/path/to/sample.mp4" \
  --form frames=5 \
  --form with_xai=true \
  --form with_llm_xai=true \
  --form llm_xai_language=english
```

> [!NOTE]
>
> Se la XAI non è inclusa nel tuo piano tariffario, il parametro `with_xai` viene ignorato e il video viene analizzato 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 il video e non vengono consumati crediti.

### Mappe XAI e spiegazioni nei risultati

Come per le immagini, le `explanations` elencano ogni mappa XAI di ciascun modello con la sua spiegazione AI, e sono restituite nei risultati per modello di ogni frame analizzato (`results.images[].results[].explanations`), con lo stesso [formato usato per le immagini](https://docs.identifai.net/it/classification/classify-image.md#mappe-xai-e-spiegazioni-nei-risultati). Le spiegazioni AI sono [risultati differiti](https://docs.identifai.net/it/api-reference/deferred-results.md), prodotti dopo l'analisi principale del video: ogni frame analizzato in `results.images` ha il proprio `deferred_status`, e `description` è `null` finché la spiegazione della mappa non è disponibile, quando le spiegazioni AI non sono state richieste o quando non è stato possibile generare la spiegazione.

```json theme={null}
{
  "status": "done",
  "deferred_status": "done",
  "results": {
    "images": [
      {
        "identifier": "<frame_identifier>",
        "deferred_status": "done",
        "results": [
          {
            "model": "Revelio",
            "classification": [
              { "label": "human", "score": 0.05 },
              { "label": "artificial", "score": 0.95 }
            ],
            "explanations": [
              {
                "type": "attention_map",
                "method": "legrad",
                "description": "The attention is concentrated on the face of the speaker, in particular around the mouth, where the movement is not consistent with the rest of the scene."
              },
              {
                "type": "attention_graph",
                "method": "legrad",
                "description": null
              }
            ]
          }
        ]
      }
    ]
  }
}
```

Le spiegazioni sono restituite solo dall'endpoint del [singolo risultato della classificazione video](https://docs.identifai.net/it/api-reference/classification/get-classification-result-video.md), e solo se il tuo piano tariffario espone i dettagli dei modelli. Le spiegazioni AI vengono addebitate per ogni frame analizzato, e i crediti dei frame le cui spiegazioni non è possibile generare vengono rimborsati.

### Scarica Attention Map e Attention Graph

L'Attention Map e l'Attention Graph di ogni frame analizzato possono essere scaricati con l'[endpoint per scaricare le mappe XAI](https://docs.identifai.net/it/api-reference/classification/get-classification-xai.md), come [per le immagini](https://docs.identifai.net/it/classification/classify-image.md#scarica-attention-map-e-attention-graph), usando l'`identifier` del frame in `results.images`:

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

> [!TIP]
>
> Quando la XAI è combinata con la [Smart Full Analysis](#smart-full-analysis), la heatmap di ogni frame 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), usando l'`identifier` del frame.

## Linee guida per interpretare i risultati

I risultati del video contengono sia i verdetti globali sia il risultato dei
singoli frame analizzati. Ti consigliamo di consultare
[come interpretare i risultati delle immagini](https://docs.identifai.net/it/classification/classify-image.md).

## Heatmap sui video

Per le heatmap sui video valgono le stesse considerazioni fatte per le [immagini](https://docs.identifai.net/it/classification/classify-image.md).
L'unica differenza è che per analizzare la heatmap devi fare clic su Frame e
analizzare la heatmap di ogni singolo frame.

### Vedi anche

> [card] [Classifica un'immagine](https://docs.identifai.net/it/classification/classify-image.md)
>
> Avvia la classificazione di un'immagine e scopri se è reale o generata 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.