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

# Clasifica una imagen

> Cómo iniciar la clasificación de una imagen

Puedes clasificar una imagen a partir de un **archivo** o de una **URL**.
\
&#x20;Esta sección explica cómo realizar la solicitud con un archivo. Con una URL el proceso es similar: la diferencia principal es el [endpoint](https://docs.identifai.net/es/api-reference/classification/submit-image-from-url.md) que hay que llamar en el *paso 1*.

## Directrices de envío

Dada la gran variabilidad de las imágenes, te recomendamos seguir estas sencillas directrices:

* Envía al sistema la imagen más "cercana" a la fuente: por ejemplo, no envíes capturas de pantalla ni fotos de pantallas.
* Los modelos de análisis de imágenes no están entrenados actualmente para reconocer fotos de documentos: por lo tanto, si envías imágenes de este tipo, el resultado no es fiable.
* En el caso de imágenes tomadas de redes sociales, los resultados más precisos se obtienen enviando imágenes sin textos superpuestos ni las modificaciones típicas de la publicación en redes sociales.
* Si la imagen está disponible en otras fuentes, evita enviar enlaces de redes sociales, debido al posprocesamiento que aplican las distintas plataformas.

## Envía una imagen mediante la API

Para clasificar una imagen, realiza una solicitud **POST** a `/api/classification` con los parámetros obligatorios (para más detalles sobre los parámetros, consulta la sección [Referencia de la API](https://docs.identifai.net/es/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
```

En la respuesta recibirás el identificador de la imagen clasificada.

> [!TIP]
>
> ¡También puedes [clasificar una imagen desde una URL](https://docs.identifai.net/es/api-reference/classification/submit-image-from-url.md)!

### Obtén los resultados

Usa el identificador recibido para obtener los resultados de la clasificación con una solicitud **GET** a `/api/classification/{identifier}` (para más detalles sobre cómo estructurar la solicitud, consulta la sección [Referencia de la API](https://docs.identifai.net/es/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 respuesta contiene los resultados de la clasificación de la imagen en formato JSON. En la respuesta encontrarás un array results, con los resultados de la clasificación de cada modelo usado, y un array verdicts, con los resultados de cada heurística aplicada.

> [!NOTE]
>
> ¡Puede que la clasificación todavía no haya terminado! Si aún no se ha completado, sigue enviando la solicitud GET hasta que el resultado esté disponible.

## Heatmap

La funcionalidad de heatmap (proporcionada por el modelo Ardē) ayuda a analizar
los detalles de la imagen. Una imagen enviada sin heatmap podría detectarse como
humana, mientras que el análisis de la misma imagen con heatmap podría poner de
manifiesto rasgos artificiales. Esto se debe a cómo los modelos interpretan las
imágenes que reciben como entrada.

Si la heatmap está disponible para tu usuario, puedes solicitar el análisis con heatmap pasando el argumento `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
```

El cálculo de la heatmap tarda un poco. Al terminar, el resultado incluirá también un modelo llamado `Ardē`:

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

El valor `score` representa el área total humana o artificial. En el ejemplo,
el resultado indica que el 20% de la imagen se ha clasificado como artificial.

También puedes descargar la heatmap como imagen coloreada usando el [endpoint](https://docs.identifai.net/es/api-reference/classification/get-classification-heatmap.md) correspondiente.

## Smart Full Analysis

Smart Full Analysis es un modo de análisis avanzado diseñado para sacar el máximo partido al proceso de clasificación de imágenes.

Un algoritmo de puntuación propietario identifica y selecciona automáticamente las áreas de la imagen con mayor contenido informativo, para que el análisis se centre en los detalles más relevantes. El enfoque funciona como un mapa de detección optimizado:

1. la imagen se divide en una selección específica de recortes de alto valor;
2. cada recorte es analizado y clasificado por el modelo más avanzado disponible de la familia **Revelio**;
3. los resultados de cada recorte se combinan en un veredicto global, teniendo en cuenta la información recogida en las distintas áreas de la imagen.

El resultado es un análisis más selectivo, eficiente y profundo, que aprovecha al máximo los modelos Revelio.

> [!NOTE]
>
> Smart Full Analysis es una versión avanzada e inteligente tanto del análisis completo estándar como de la [heatmap](#heatmap): cuando está activado, **sustituye a ambos**.

> [!WARNING]
>
> `with_smart_analysis` y `with_heatmap` no se pueden combinar: una solicitud con ambos en `true` se rechaza con un error `422`.

Si Smart Full Analysis está incluido en tu plan de precios, puedes activarlo con el argumento `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]
>
> Si Smart Full Analysis no está incluido en tu plan de precios, el parámetro `with_smart_analysis` se ignora y la imagen se analiza con el scope estándar.

## XAI (eXplainable AI)

**No solo un veredicto. Descubre qué observó la inteligencia artificial para llegar a su decisión.**

¿Por qué Revelio clasificó una imagen o un vídeo como generado por IA? ¿Qué elementos del contenido llamaron más su atención?

Con la nueva funcionalidad **XAI – eXplainable AI**, identifAI da un paso más hacia una mayor transparencia e interpretabilidad de sus modelos de clasificación.

XAI es un nuevo scope de análisis que enriquece los veredictos de Revelio con un conjunto de herramientas visuales y descriptivas, diseñadas para ayudarte a entender dónde centró su atención el modelo durante el análisis.

### De la clasificación a la comprensión

Cuando XAI está activado, los modelos Revelio no se limitan a devolver un veredicto: también generan información sobre los puntos de atención que caracterizaron el proceso de clasificación.

Esta información se convierte en tres herramientas complementarias:

> [card] Attention Map
>
> **Ve dónde se concentra la atención.** Una representación visual superpuesta al contenido original, que resalta las áreas en las que más se centró el modelo. Una forma inmediata e intuitiva de explorar lo que observó Revelio.

> [card] Attention Graph
>
> **Explora el análisis en profundidad.** Un gráfico que muestra la evolución y los picos de la atención del modelo, con una perspectiva más técnica y detallada para quien quiera profundizar en el comportamiento del algoritmo.

> [card] Explicación impulsada por IA
>
> **De las imágenes a las palabras.** Una descripción en lenguaje natural de las regiones que recibieron más atención, disponible en varios idiomas, para que la información producida por el modelo sea aún más accesible y fácil de interpretar.

### Más transparencia, más herramientas para interpretar los resultados

Con XAI, identifAI ofrece nueva información para apoyar la interpretación de los resultados, complementando la clasificación tradicional con una perspectiva visual, analítica y descriptiva.

Un paso adelante hacia una inteligencia artificial cada vez más transparente, comprensible y accesible.

### Disponible en la plataforma web y mediante API

XAI está disponible actualmente para el análisis de imágenes y de [vídeos](https://docs.identifai.net/es/classification/classify-video.md#xai-explainable-ai), tanto en la plataforma web de identifAI como mediante API, para que puedas integrarlo fácilmente en tus flujos de trabajo.

> [!NOTE]
>
> **¿Y el audio?** ¡Estamos trabajando en ello! Nuestro objetivo es extender pronto estas capacidades también al análisis de contenidos de audio.

> [!WARNING]
>
> **Aviso sobre la transferencia de datos:** al activar esta funcionalidad, tus datos de imagen se transfieren a nuestra infraestructura cloud en la UE para la inferencia de los modelos.
>
> Las explicaciones impulsadas por IA se generan con modelos no desarrollados por identifAI.

### Activa XAI mediante la API

XAI se controla con los siguientes parámetros de la [API para la clasificación de imágenes](https://docs.identifai.net/es/api-reference/classification/submit-an-image-for-classification.md) y de la [API para la clasificación de imágenes desde URL](https://docs.identifai.net/es/api-reference/classification/submit-image-from-url.md):

| Parámetro | Descripción |
| - | - |
| `with_xai` | Establécelo en `true` para activar el scope XAI. |
| `with_llm_xai` | Establécelo en `true`, junto con `with_xai`, para obtener también las **explicaciones impulsadas por IA**. Se ignora si `with_xai` no está activado. |
| `llm_xai_language` | Idioma de las explicaciones impulsadas por IA: `english`, `italian`, `spanish` o `german` (sin distinguir mayúsculas y minúsculas). Si se omite, se usa el idioma predeterminado de tu plan de precios. |

Si XAI está incluido en tu plan de precios, puedes activarlo, junto con las explicaciones impulsadas por IA en italiano, así:

```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]
>
> Si XAI no está incluido en tu plan de precios, el parámetro `with_xai` se ignora y la imagen se analiza sin XAI.

> [!WARNING]
>
> Las explicaciones impulsadas por IA también deben estar activadas en tu plan de precios: si tu plan incluye XAI pero no las explicaciones impulsadas por IA, una solicitud con `with_llm_xai=true` se rechaza con un error `403`. Un `llm_xai_language` no admitido se rechaza con un error `400`. En ambos casos la solicitud se rechaza antes de analizar la imagen y no se consumen créditos.

### Mapas y explicaciones XAI en los resultados

Cuando XAI está activado, cada resultado por modelo en `results` que haya producido al menos un mapa XAI contiene un array `explanations`, que enumera **todos los mapas** del modelo, con su explicación impulsada por IA:

```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 | Descripción |
| - | - |
| `type` | El mapa XAI: `attention_map`, `attention_graph` o `heatmap` |
| `method` | El método XAI usado para calcular el mapa (`legrad`, `transformer_attribution` o `attention_rollout`); `null` para `heatmap` |
| `description` | Descripción en lenguaje natural de las regiones que recibieron más atención, en el idioma solicitado con `llm_xai_language`, o `null` cuando no está disponible (ver más abajo) |

Las explicaciones impulsadas por IA son [resultados diferidos](https://docs.identifai.net/es/api-reference/deferred-results.md): se producen después del análisis principal, sin retrasarlo. El veredicto, los resultados de clasificación y la lista de los mapas XAI están disponibles en cuanto el `status` del envío pasa a `done`, mientras que las descripciones se completan después: sigue el campo `deferred_status` del [resultado de la clasificación](https://docs.identifai.net/es/api-reference/classification/get-classification-result.md), o establece `deferred_webhook_url` para recibir una notificación cuando estén completas.

`description` es `null` cuando:

* no se solicitaron las explicaciones impulsadas por IA (`with_llm_xai` no establecido): los mapas se enumeran de todos modos, para que puedas [descargarlos](#descarga-el-attention-map-y-el-attention-graph);
* la explicación aún no está disponible, porque los resultados diferidos todavía están en curso;
* la explicación se solicitó pero no se pudo generar. Si esto ocurre por un error técnico, `deferred_status` es `errored`, mientras que las explicaciones generadas para los demás mapas se siguen devolviendo: consulta [Resultados diferidos](https://docs.identifai.net/es/api-reference/deferred-results.md). Los créditos de las explicaciones impulsadas por IA que no se pueden generar se reembolsan.

Ten en cuenta que:

* las explicaciones solo las devuelve el endpoint del [resultado de una clasificación](https://docs.identifai.net/es/api-reference/classification/get-classification-result.md): no se incluyen en las listas de clasificaciones ni en el payload enviado a `webhook_url`. La notificación enviada a `deferred_webhook_url` contiene las descripciones en sus campos `xai` y `heatmaps`;
* los `results` por modelo, y por tanto las explicaciones, solo se devuelven si tu plan de precios expone los detalles de los modelos;
* cuando se solicita la [heatmap](#heatmap), aparece con `type` `heatmap` (y `method` `null`) en el resultado del modelo `Ardē`; cuando está activado el [Smart Full Analysis](#smart-full-analysis), su heatmap aparece en los resultados de los modelos que la produjeron.

### Descarga el Attention Map y el Attention Graph

El Attention Map y el Attention Graph se pueden descargar como imágenes con el [endpoint de descarga de los mapas XAI](https://docs.identifai.net/es/api-reference/classification/get-classification-xai.md), indicando el `model` que produjo el mapa (tal como aparece en el campo `model` de los resultados por modelo), el `method` XAI (`legrad`, `transformer_attribution` o `attention_rollout`) y el `type` de mapa (`attention_map`, el predeterminado, 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
```

Los mapas producidos dependen del modelo: las `explanations` de cada resultado por modelo enumeran el `type` y el `method` de cada mapa disponible, también cuando no se solicitaron las explicaciones impulsadas por IA. Si no hay ningún mapa disponible para el modelo, el método y el tipo solicitados, el endpoint devuelve un error `404`.

> [!TIP]
>
> Cuando XAI se combina con el [Smart Full Analysis](#smart-full-analysis), su heatmap se puede descargar como siempre con el [endpoint de descarga de la heatmap](https://docs.identifai.net/es/api-reference/classification/get-classification-heatmap.md).

## Directrices para interpretar los resultados

Para interpretar el resultado, te recomendamos centrarte en:

* Revelio como resultado principal para el veredicto (la opción predeterminada de la plataforma), con mayor fiabilidad si hay rostros y personas.
* Aide para un análisis detallado con el apoyo de la funcionalidad de heatmap.
* Morphing, que solo debe tenerse en cuenta si hay rostros.
* Ellen, si la imagen procede de fuentes en las que se ha comprobado en el pasado el uso de herramientas de retoque fotográfico.
* V01 y Brokenwand solo en el caso de imágenes muy antiguas (y por tanto potencialmente generadas con sistemas que ya no se usan hoy).

Además, para el análisis con heatmap te recomendamos:

* Prestar mucha atención al tamaño de las imágenes enviadas: el análisis con
  heatmap es especialmente exigente desde el punto de vista computacional y el
  tiempo de procesamiento aumenta considerablemente según el tamaño de la imagen.
  Las directrices recomiendan enviar imágenes con una resolución inferior a 2k (o 4 megapíxeles).

## Ver también

> [card] [Clasifica un vídeo](https://docs.identifai.net/es/classification/classify-video.md)
>
> Descubre cómo iniciar la clasificación de un vídeo y saber si es auténtico o generado artificialmente

> [card] [Clasifica un audio de voz](https://docs.identifai.net/es/classification/classify-speech.md)
>
> Descubre cómo iniciar la clasificación de un audio de voz y saber si es auténtico o generado artificialmente


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