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

# Valida un file multimediale

> Verifica se un file immagine, video o audio può essere analizzato, **senza inviarlo per la classificazione**: il file non viene salvato, non viene avviata alcuna classificazione e **non vengono consumati crediti**.

Il file viene verificato rispetto ai requisiti dei modelli che lo analizzerebbero. Questi modelli vengono determinati esattamente come negli endpoint di classificazione, in base al tuo piano tariffario e alle opzioni inviate con la richiesta: per ottenere un risultato significativo, invia le stesse opzioni (ad es. `with_morphing`, `with_heatmap`, `with_audio`) che userai per l'invio effettivo.

I controlli eseguiti sono:

- **Tipo e dimensione del file**: gli stessi formati e limiti dell'endpoint di classificazione corrispondente ([immagine](./submit-an-image-for-classification), [video](./submit-a-video-for-classification), [audio](./submit-a-speech-for-classification)).
- **Risoluzione minima** (immagini e video): il lato corto del media deve rispettare la dimensione minima richiesta da ogni modello selezionato.
- **Risoluzione video minima** (solo video): l'altezza del video deve rispettare la risoluzione minima supportata dalla piattaforma (ad es. 720p).

L'esito è sempre riportato nel campo `valid` della risposta: `true` con stato `200` quando il media può essere analizzato, `false` con stato `422` o `413` quando non può esserlo, insieme a un `detail` che ne spiega il motivo.



## OpenAPI

````yaml it/api-reference/api-swagger-dev-documentation.json POST /api/validate
openapi: 3.0.0
info:
  title: API di identifAI
  version: 1.0.0
  description: >-
    API per integrare le funzionalità di classificazione di immagini e video di
    identifAI.<br><details><summary>**Come ottenere la tua API
    key**</summary>Per ottenere la tua API key, segui questi semplici
    passaggi:   <ol><li><p>**Crea un profilo utente e accedi alla
    piattaforma**</p>Se non hai ancora un account, visita la nostra piattaforma
    e crea un profilo utente. Dopo aver completato la registrazione e verificato
    la tua e-mail, accedi con le tue credenziali.</li><li><p>**Apri il menu
    utente**</p>Dopo l'accesso, fai clic sul tuo nome o sull'icona utente in
    alto a destra nello schermo.</li><li><p>**Seleziona la voce API key**</p>Nel
    menu a tendina che compare, seleziona la voce "Api-Key". Da lì puoi
    visualizzare o generare la tua API key.</li></ol>Ora sei pronto per usare la
    tua API key con la nostra API!</details><details><summary>**Come usare
    l'API**</summary>Per usare l'API, effettua prima una richiesta **POST** per
    avviare la classificazione. Poi usa l'***identificativo*** restituito dalla
    richiesta **POST** per recuperare i risultati.

    <details>

    <summary>**1. Classificazione delle immagini**</summary>
      * Per classificare un'immagine, effettua una richiesta **POST** a `/api/classification` con i parametri richiesti (per i dettagli sui parametri consulta la sezione *"Classificazione"* qui sotto).
      * Nella risposta riceverai l'***identificativo*** dell'immagine classificata.
      * 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 *"Classificazione"* qui sotto).
      * La risposta contiene i risultati della classificazione dell'immagine in formato JSON.<br>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.<br>Se la classificazione non è ancora completa, continua a inviare la richiesta **GET** finché il risultato non è disponibile.</details><details><summary>**2. Classificazione dei video**</summary>
        * Per classificare un video, effettua una richiesta **POST** a `/api/classification_video` con i parametri richiesti (per i dettagli sui parametri consulta la sezione *"Classificazione"* qui sotto).
        * Nella risposta riceverai l'***identificativo*** del video classificato.
        * 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 *"Classificazione"* qui sotto).
        * La risposta contiene i risultati della classificazione del video in formato JSON. Per la classificazione, il video viene suddiviso in *frame*.<br> 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.<br> Se la classificazione non è completa, continua a inviare la richiesta **GET** finché non vengono restituiti i risultati finali.</details><details><summary>**3. Tutte le classificazioni**</summary>L'endpoint `/api/classifications` restituisce tutte le classificazioni di immagini effettuate da un utente, con i risultati di tutte le richieste di classificazione di immagini passate.</details><details><summary>**4. Gestione degli utenti**</summary>  L'endpoint **POST** `/api/user` permette di creare un utente, mentre l'endpoint **DELETE** `/api/user` serve a eliminare un utente (per la struttura delle richieste consulta la sezione sugli utenti qui sotto).</details></details>
servers:
  - url: https://backend.identifai.net
security: []
tags:
  - name: Classification
    description: Route di classificazione
  - name: Infrastructure
    description: Route dell'infrastruttura
  - name: User
    description: Azioni dell'utente
  - name: Partner
    description: Azioni dei partner
paths:
  /api/validate:
    post:
      tags:
        - Classification
      summary: Valida un file multimediale
      description: >-
        Verifica se un file immagine, video o audio può essere analizzato,
        **senza inviarlo per la classificazione**: il file non viene salvato,
        non viene avviata alcuna classificazione e **non vengono consumati
        crediti**.


        Il file viene verificato rispetto ai requisiti dei modelli che lo
        analizzerebbero. Questi modelli vengono determinati esattamente come
        negli endpoint di classificazione, in base al tuo piano tariffario e
        alle opzioni inviate con la richiesta: per ottenere un risultato
        significativo, invia le stesse opzioni (ad es. `with_morphing`,
        `with_heatmap`, `with_audio`) che userai per l'invio effettivo.


        I controlli eseguiti sono:


        - **Tipo e dimensione del file**: gli stessi formati e limiti
        dell'endpoint di classificazione corrispondente
        ([immagine](./submit-an-image-for-classification),
        [video](./submit-a-video-for-classification),
        [audio](./submit-a-speech-for-classification)).

        - **Risoluzione minima** (immagini e video): il lato corto del media
        deve rispettare la dimensione minima richiesta da ogni modello
        selezionato.

        - **Risoluzione video minima** (solo video): l'altezza del video deve
        rispettare la risoluzione minima supportata dalla piattaforma (ad es.
        720p).


        L'esito è sempre riportato nel campo `valid` della risposta: `true` con
        stato `200` quando il media può essere analizzato, `false` con stato
        `422` o `413` quando non può esserlo, insieme a un `detail` che ne
        spiega il motivo.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - image
                    - video
                    - audio
                  description: >-
                    Il tipo di media da validare. La validazione di video e
                    audio richiede la stessa abilitazione degli endpoint di
                    classificazione corrispondenti.
                file:
                  type: string
                  format: binary
                  description: >-
                    Il file multimediale da validare. I formati supportati e la
                    dimensione massima dipendono da `type` e sono gli stessi
                    dell'endpoint di classificazione corrispondente:
                    [immagine](./submit-an-image-for-classification),
                    [video](./submit-a-video-for-classification),
                    [audio](./submit-a-speech-for-classification).
                with_morphing:
                  type: boolean
                  description: >-
                    Solo immagini e video. Impostalo a true per validare il file
                    anche rispetto ai modelli usati per analizzare i volti delle
                    persone (morphing).
                with_tampering:
                  type: boolean
                  description: >-
                    Solo immagini e video. Impostalo a true per validare il file
                    anche rispetto ai modelli usati per analizzare i segni di
                    manomissione o manipolazione.
                with_heatmap:
                  type: boolean
                  description: >-
                    Solo immagini. Impostalo a true per validare il file anche
                    rispetto ai modelli usati per produrre la heatmap dei
                    contenuti generati dall'IA.
                with_nsfw:
                  type: boolean
                  description: >-
                    Solo immagini e video. Impostalo a true per validare il file
                    anche rispetto ai modelli usati per il rilevamento dei
                    contenuti NSFW (Not Safe For Work).
                with_audio:
                  type: boolean
                  description: >-
                    **[BETA]** Solo video. Impostalo a true per validare il file
                    anche rispetto ai modelli usati per analizzare la traccia
                    audio del video. **Per usarlo deve essere abilitato nel tuo
                    piano tariffario**, altrimenti il parametro viene ignorato.
              required:
                - type
                - file
      responses:
        '200':
          description: >-
            Il media è valido e può essere inviato per la classificazione con le
            opzioni indicate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaValidation'
              examples:
                image:
                  summary: Immagine valida
                  value:
                    valid: true
                    filesize: 1048576
                    mimetype: image/jpeg
                    width: 1920
                    height: 1080
                    models:
                      - image_model_a
                      - image_model_b
                audio:
                  summary: Audio valido
                  value:
                    valid: true
                    filesize: 524288
                    mimetype: audio/mpeg
                    width: null
                    height: null
                    models:
                      - audio_model_a
        '400':
          description: >-
            La richiesta contiene parametri errati: `type` mancante o non
            supportato, `file` mancante, oppure un file il cui formato o la cui
            dimensione non sono accettati per il `type` indicato.
          content:
            application/json:
              examples:
                invalid_type:
                  value:
                    error:
                      type:
                        - The selected type is invalid.
                missing_file:
                  value:
                    error:
                      file:
                        - The file field is required.
                invalid_image_format:
                  value:
                    error:
                      file:
                        - >-
                          The file must be a file of type: png, jpg, jpeg, gif,
                          webp, tif, tiff.
                not_a_video:
                  value:
                    error:
                      file:
                        - The file must be a video file.
        '401':
          description: API key non valida o mancante.
          content:
            application/json:
              example:
                error: Unauthorized
        '403':
          description: >-
            L'utente non è autorizzato ad accedere a questa API, non ha
            accettato i Termini di servizio o non è abilitato alla
            classificazione del `type` di media richiesto (video o audio).
          content:
            application/json:
              example:
                error: Unauthorized
        '413':
          description: >-
            Il media non è valido: la dimensione del file supera quella massima
            consentita per il `type` richiesto.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaValidationError'
              example:
                valid: false
                detail: >-
                  The image file size (73400320 bytes) exceeds the maximum
                  allowed size of 52428800 bytes.
        '422':
          description: >-
            Il media non è valido e non può essere analizzato con le opzioni
            indicate (ad es. file danneggiato, risoluzione troppo bassa per i
            modelli selezionati), oppure nel tuo piano tariffario non ci sono
            modelli disponibili per le opzioni selezionate.
          content:
            application/json:
              examples:
                corrupted_file:
                  summary: File danneggiato
                  value:
                    valid: false
                    detail: >-
                      Invalid or corrupted image file: cannot identify image
                      file
                quality_requirements:
                  summary: Risoluzione troppo bassa per i modelli selezionati
                  value:
                    valid: false
                    detail: >-
                      Media does not meet the quality requirements for the
                      requested models: 'image_model_a' requires a minimum size
                      of 256px, got 128px.
                video_resolution:
                  summary: Risoluzione del video troppo bassa
                  value:
                    valid: false
                    detail: >-
                      Video resolution too low: got 640x360, minimum required
                      height is 720px (720p).
                not_an_audio:
                  summary: Non è un file audio
                  value:
                    valid: false
                    detail: >-
                      Invalid file type. Must be an audio file: sample.mp3,
                      application/octet-stream
                no_models:
                  summary: Nessun modello disponibile per le opzioni selezionate
                  value:
                    message: No available models for the selected options
        '429':
          description: Troppe richieste.
          content:
            application/json:
              example:
                message: Too Many Attempts.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    MediaValidation:
      type: object
      properties:
        valid:
          type: boolean
          description: >-
            Sempre `true` per una validazione riuscita: il media può essere
            inviato per la classificazione con le opzioni indicate.
        filesize:
          type: integer
          description: Dimensione del file validato, in byte.
        mimetype:
          type: string
          description: >-
            Tipo MIME rilevato dal contenuto del file (ad es. `image/jpeg`,
            `video/mp4`, `audio/mpeg`).
        width:
          type: integer
          nullable: true
          description: Larghezza del media in pixel. `null` per i file audio.
        height:
          type: integer
          nullable: true
          description: Altezza del media in pixel. `null` per i file audio.
        models:
          type: array
          description: >-
            Identificativi dei modelli rispetto ai quali è stato validato il
            media, determinati in base al tuo piano tariffario e alle opzioni
            selezionate.
          items:
            type: string
      required:
        - valid
        - filesize
        - mimetype
        - models
    MediaValidationError:
      type: object
      properties:
        valid:
          type: boolean
          description: >-
            Sempre `false`: il media non può essere analizzato con le opzioni
            indicate.
        detail:
          type: string
          description: Motivo leggibile per cui il media non è valido.
      required:
        - valid
        - detail
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-Api-Key
      in: header
      description: La tua API key.

````

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