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

# Risultati differiti

> Alcuni risultati di un invio, come le spiegazioni testuali delle mappe XAI e della heatmap, vengono prodotti dopo i risultati principali. Scopri come seguirli e come ricevere una notifica quando sono completi.

# Risultati differiti

L'analisi di un invio ha due fasi:

1. l'**analisi principale** produce il verdetto e i risultati della classificazione. Al suo termine, lo `status` dell'invio diventa `done` (o `errored`) e i risultati principali vengono inviati a `webhook_url` e ai tuoi webhook, come prima;
2. i **risultati differiti** vengono prodotti in seguito, senza ritardare i risultati principali. Oggi sono le spiegazioni AI delle mappe XAI e della heatmap, richieste con `with_xai` e `with_llm_xai` (vedi [XAI – eXplainable AI](https://docs.identifai.net/it/classification/classify-image.md#xai-explainable-ai)) e restituite nella `description` delle `explanations` dei risultati per modello.

I risultati differiti non cambiano mai il verdetto, i risultati della classificazione né lo `status` dell'invio.

## Seguire i risultati differiti

Quando un invio ha risultati differiti, il risultato della classificazione (`GET /api/classification/{identifier}`, `GET /api/classification_video/{identifier}`, `GET /api/classification_audio/{identifier}`) contiene anche:

| Campo | Descrizione |
| - | - |
| `deferred_status` | `pending` (analisi principale ancora in corso), `inprogress`, `done`, `errored` (almeno un passaggio differito è fallito: i risultati principali restano validi), `skipped` (l'analisi principale è fallita), `expired` (non completati in tempo) |
| `deferred_progress` | `{ "current_idx": 1, "total": 2 }`: passaggi differiti completati finora, sul totale |
| `deferred_errors` | Messaggi pubblici dei passaggi differiti falliti |

Per i video, ogni frame analizzato in `results.images` ha il proprio `deferred_status`. I campi sono assenti negli invii senza risultati differiti.

> [!NOTE]
>
> `expired` non è definitivo: se i risultati differiti si completano dopo la scadenza, `deferred_status` diventa `done` o `errored`.

> [!NOTE]
>
> `errored` non significa che non sia disponibile nessuna spiegazione. Quando alcune spiegazioni delle mappe XAI o della heatmap non possono essere generate a causa di un errore tecnico, `deferred_status` è `errored` e `deferred_errors` contiene `Some explanations of the XAI maps could not be generated`, mentre le spiegazioni generate per le altre mappe vengono comunque restituite in `explanations`. Le mappe senza spiegazione restano in `explanations` con `description` impostato a `null`; anche una mappa che il modello non è in grado di descrivere ha `description` `null`, e non è un errore.

## Notifica dei risultati differiti

Per ricevere una notifica quando i risultati differiti sono completi, imposta `deferred_webhook_url` quando invii un'immagine, un video o un audio vocale (anche da URL). Funziona come `webhook_url`: richiede la stessa abilitazione e ha le stesse restrizioni sui domini e la stessa autenticazione. Se è omesso o vuoto, non viene inviata nessuna notifica.

Puoi abilitare la notifica anche sui webhook configurati nella dashboard, con **Notifica i risultati differiti** e un URL dedicato opzionale. La notifica viene inviata solo ai webhook che hanno ricevuto il risultato principale dell'invio: ad esempio, un webhook che notifica solo i risultati artificiali non riceve nessuna notifica differita per un risultato umano.

La notifica viene inviata **una sola volta**, quando i risultati differiti diventano `done`, `errored` o `expired`: non viene inviata per i singoli passaggi, né quando l'analisi principale è fallita (`skipped`). Per un video, viene inviata dopo l'ultimo frame.

```json theme={null}
{
  "event": "submission.deferred.completed",
  "version": 1,
  "sent_at": "2026-10-27T12:00:00.000Z",
  "submission": {
    "identifier": "8f0c2d3e9b1a4c7d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5",
    "type": "image",
    "status": "done",
    "deferred_status": "done",
    "deferred_progress": { "current_idx": 1, "total": 1 },
    "completed_at": "2026-10-27T11:58:41.000Z",
    "deferred_completed_at": "2026-10-27T11:59:58.000Z",
    "deferred_errors": [],
    "xai": [
      {
        "model": "...",
        "method": "legrad",
        "type": "attention_map",
        "artifact": "...",
        "description": "The model focuses on the skin texture around the eyes and on the hairline, where the generated details are less consistent."
      }
    ],
    "heatmaps": [
      {
        "model": "...",
        "artifact": "...",
        "description": "The highlighted area around the mouth shows signs of manipulation."
      }
    ],
    "frames": []
  }
}
```

| Campo | Descrizione |
| - | - |
| `event` | Sempre `submission.deferred.completed` |
| `version` | Versione del payload, incrementata in caso di modifiche incompatibili |
| `sent_at` | Quando è stata inviata la notifica |
| `submission.identifier` | Lo stesso `identifier` restituito all'invio e inviato nella notifica principale |
| `submission.type` | `image`, `audio` o `video` |
| `submission.status` | Stato dell'analisi principale |
| `submission.deferred_status` | `done`, `errored` o `expired` |
| `submission.deferred_errors` | Messaggi pubblici dei passaggi differiti falliti |
| `submission.xai` | Spiegazioni testuali delle mappe XAI |
| `submission.heatmaps` | Spiegazioni testuali delle heatmap |
| `submission.frames` | Solo video: `hash`, `name`, `status`, `deferred_status`, `xai` e `heatmaps` di ogni frame |

> [!WARNING]
>
> La consegna è **almeno una volta**: la stessa notifica può arrivare più di una volta, quindi deduplicala per `identifier` e `deferred_status`. Una notifica `expired` può essere seguita da una seconda notifica con l'esito reale (`done` o `errored`): quella successiva sostituisce la precedente.


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