# Detecciones de imágenes

> Detecte si una imagen entera fue generada por IA con POST /images/detections. Una llamada síncrona: campos de la solicitud y la respuesta, valores de la respuesta, límites y facturación.

Fuente: https://fileverity.com/es/docs/image-detections

`POST /images/detections` ejecuta la detección de imágenes IA. Indica si una imagen entera fue generada por IA con `vereye-2-detect`, con los mismos modelos, Credenciales de contenido (Content Credentials), etiquetas de IA y marcas de agua que el informe de verificación de imagen (`vereye-2`), por lo que ambos dan la misma respuesta sobre la generación por IA. Es síncrono: el resultado va en la respuesta.

No examina las ediciones locales, incluidas las que haga una IA en una parte de la foto, y no devuelve ID de informe ni PDF. Para ediciones, procedencia y un registro que cualquiera pueda verificar, cree un [análisis](https://fileverity.com/es/docs/analyses.md) con `vereye-2`.

**Solicitud: cURL**

```bash
curl https://api.fileverity.com/v1/images/detections \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Idempotency-Key: 6b9d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e11" \
  -F file=@photo.jpg
```

**Solicitud: JavaScript**

```javascript
import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const form = new FormData();
form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");

const response = await fetch("https://api.fileverity.com/v1/images/detections", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Idempotency-Key": randomUUID() },
  body: form,
});
const detection = await response.json();
console.log(detection.verdict, detection.ai);
```

**Solicitud: Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.fileverity.com/v1/images/detections",
    headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    files={"file": open("photo.jpg", "rb")},
)
detection = response.json()
print(detection["verdict"], detection["ai"])
```

## Cuerpo de la solicitud

Envíe la imagen como `multipart/form-data` en el campo `file`, de hasta 4 MB. Para imágenes mayores, de hasta 10 MB, súbalas antes con [`POST /files`](https://fileverity.com/es/docs/files.md) y envíe JSON en su lugar:

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `file` | cadena o archivo | Sí | La imagen en una solicitud multipart, o el ID de una imagen subida en una solicitud JSON. JPEG, PNG, WEBP, hasta 40 megapíxeles. La comprobación consume el ID de archivo. |
| `model` | cadena | No | Valor predeterminado: `vereye-2-detect`. Acepta el ID del modelo o el ID de su versión fechada `vereye-2-detect-2026-10-30`. |

Los campos desconocidos se rechazan con `invalid_parameter`.

## Respuesta

**200 OK**

```json
{
  "id": "idet_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "image.detection",
  "created": 1794096000,
  "model": "vereye-2-detect-2026-10-30",
  "livemode": true,
  "verdict": "ai_generated",
  "ai": {
    "key": "very_likely",
    "basis": "detected",
    "strength": "strong",
    "likelihood": 100
  },
  "generator": null,
  "signals": [
    {
      "id": "model_1",
      "state": "ai"
    },
    {
      "id": "model_2",
      "state": "ai"
    },
    {
      "id": "credentials",
      "state": "none"
    },
    {
      "id": "watermark",
      "state": "none"
    },
    {
      "id": "label",
      "state": "none"
    },
    {
      "id": "tool_data",
      "state": "none"
    },
    {
      "id": "camera",
      "state": "none"
    }
  ],
  "regions": [
    {
      "x": 0,
      "y": 0,
      "w": 576,
      "h": 512,
      "level": 3
    },
    {
      "x": 576,
      "y": 0,
      "w": 384,
      "h": 512,
      "level": 3
    },
    {
      "x": 960,
      "y": 0,
      "w": 576,
      "h": 512,
      "level": 2
    },
    {
      "x": 0,
      "y": 512,
      "w": 576,
      "h": 512,
      "level": 3
    },
    {
      "x": 576,
      "y": 512,
      "w": 384,
      "h": 512,
      "level": 3
    },
    {
      "x": 960,
      "y": 512,
      "w": 576,
      "h": 512,
      "level": 3
    }
  ],
  "candidates": [
    {
      "name": "Midjourney",
      "score": 0.65
    },
    {
      "name": "OpenAI",
      "score": 0.25
    }
  ],
  "quality": {
    "overall": "fair",
    "resolution": "good",
    "compression": "fair",
    "metadata": "fair",
    "distribution": "good"
  },
  "limits": [
    "no_metadata"
  ],
  "image": {
    "width": 1536,
    "height": 1024,
    "format": "jpeg",
    "jpeg_quality": 85
  },
  "usage": {
    "credits": 4
  }
}
```

| Campo | Tipo | Descripción |
| --- | --- | --- |
| `id` | cadena | ID de la detección, con el prefijo `idet_`. |
| `object` | cadena | Siempre `image.detection`. |
| `created` | entero | Marca de tiempo Unix. |
| `model` | cadena | Versión fechada que produjo el resultado. |
| `livemode` | booleano | `false` para las claves de prueba. |
| `verdict` | cadena | `ai_generated`: la imagen fue generada por IA. `no_ai_signs`: nada apunta a una generación por IA. `inconclusive`: las pruebas no permiten decidir. |
| `ai` | objeto | La respuesta sobre la generación por IA, con los mismos valores que `questions.ai` del [informe de imagen](https://fileverity.com/es/docs/analyses.md#report-image). |
| `generator` | objeto o null | El generador que declara el archivo mediante Credenciales de contenido, metadatos o una marca de agua, con `name` y `basis`. `null` cuando el archivo no indica ninguno. |
| `signals` | matriz | Las comprobaciones en que se basa la respuesta, cada una con `id` y `state`. Consulte [Señales](#signals). |
| `regions` | array o null | Una cuadrícula aproximada sobre la imagen. Cada celda tiene `x`, `y`, `w` y `h` en píxeles de la imagen mostrada y un `level` de 0 a 3 para la intensidad de los rasgos de generación. `null` cuando la imagen es demasiado pequeña para una cuadrícula. |
| `candidates` | matriz | Hasta tres familias de generadores a cuyos rasgos de píxeles más se parece la imagen, cada una con `name` y un `score` de 0 a 1. Vacío salvo que el veredicto sea `ai_generated`. |
| `quality` | objeto o null | Hasta qué punto el archivo permite el análisis: `overall`, `resolution`, `compression`, `metadata` y `distribution`, cada uno con valor `good`, `fair` o `poor`. |
| `limits` | matriz | Qué limita el resultado: `low_resolution`, `heavy_compression`, `platform_copy`, `no_metadata` o `models_disagree`. |
| `image` | objeto | `width` y `height` tal como se muestra, `format` y `jpeg_quality`, la calidad JPEG estimada o `null`. |
| `usage` | objeto | `credits` descontados. |

## Cómo leer la respuesta

| `ai.key` | `verdict` | Significado |
| --- | --- | --- |
| `labelled` | `ai_generated` | Las Credenciales de contenido, una etiqueta de IA o una marca de agua declaran una generación por IA. `ai.basis` es `verified` para credenciales de confianza; en los demás casos es `declared` o `detected`. |
| `very_likely`, `suspected` | `ai_generated` | Los píxeles indican una generación por IA, con claridad o con cierto desacuerdo entre señales. |
| `undecided` | `inconclusive` | Las señales son débiles o se contradicen. |
| `low`, `very_low` | `no_ai_signs` | Nada en los píxeles ni en los metadatos apunta a una generación por IA. |

`ai.strength` es `strong`, `moderate` o `limited` e indica con qué solidez respaldan las pruebas la respuesta. `ai.likelihood` va de 0 a 100 en pasos de 5 y es `null` para `labelled`.

> **Nota.** `no_ai_signs` no demuestra que una foto sea auténtica ni que no esté editada. La detección de imágenes IA no busca ediciones. Cuando una decisión dependa de ello, ejecute un informe de verificación de imagen y haga que una persona revise el resultado.

## Señales

`signals` enumera todas las comprobaciones realizadas, para que pueda ver en qué se basa la respuesta. Un `state` con valor `ai` apunta a generación con IA.

| `id` | `state` | Comprobación |
| --- | --- | --- |
| `model_1`, `model_2` | `ai`, `unclear`, `clear`, `unavailable` | Dos modelos entrenados de forma independiente que analizan los píxeles. |
| `credentials` | `ai`, `ai_unverified`, `other`, `none` | Credenciales de contenido (C2PA). `ai_unverified`: las credenciales declaran generación con IA, pero no se pudo verificar su emisor. `other`: las credenciales están presentes y no declaran generación con IA. |
| `watermark` | `ai`, `none`, `unavailable` | Marcas de agua invisibles que las herramientas de generación de código abierto incrustan en los píxeles. |
| `label` | `ai`, `none` | Una declaración de generación con IA en los metadatos, como el tipo de fuente digital de IPTC. |
| `tool_data` | `ai`, `none` | Prompts, parámetros o nombres de generadores guardados en el archivo. |
| `camera` | `present`, `none` | Marca, modelo y datos de exposición de la cámara. Pueden editarse y este endpoint no los verifica. |

`regions` muestra dónde son más marcados los rasgos de generación. Las celdas de nivel 3 tienen rasgos marcados. Cuando el veredicto es `no_ai_signs` y algunas celdas están en el nivel 3, es posible que parte de la imagen se haya generado o editado con IA: este endpoint no examina las ediciones locales, así que ejecute un informe de verificación de imagen.

> **Nota.** `candidates` es un indicio, no una identificación. Ordena las familias de generadores según lo parecidos que son sus rasgos de píxeles a los de la imagen, y un generador ajeno al conjunto de referencia aparece como su coincidencia más cercana. Base su decisión en `generator` cuando el propio archivo nombre la herramienta.

## Facturación

- La detección de imágenes IA cuesta 4 créditos por imagen.
- Un informe de verificación de imagen de la misma imagen en el mismo espacio de trabajo en un plazo de 7 días cuesta 36 créditos en lugar de 40: los créditos de la detección se descuentan una sola vez. El análisis indica el cargo en `usage.credits`.
- Las solicitudes rechazadas antes de la evaluación no se cobran: parámetros no válidos, archivos no admitidos o dañados, límites de tamaño y casos similares. Una comprobación que falla dentro del servicio (`service_unavailable`, `analysis_failed`) se libera y no se cobra.
- Si no hay créditos suficientes, se devuelve `insufficient_balance` (402).

## Qué se almacena

La imagen se examina y se elimina. Fileverity conserva el resultado sin la imagen (veredicto, respuesta, generador, señales, regiones, candidatos, calidad, dimensiones, la huella SHA-256 del archivo y el consumo) durante 7 días, para que la Consola pueda mostrarlo y el consumo pueda facturarse y auditarse. Una solicitud repetida con la misma `Idempotency-Key` recibe el resultado guardado durante 24 horas. Las detecciones de imágenes son síncronas: no aparecen en `GET /analyses` ni envían eventos de webhook. Las claves de prueba no registran nada. Consulte [Conservación de datos y seguridad](https://fileverity.com/es/docs/security.md).

## Errores

| Código | Estado | Causa |
| --- | --- | --- |
| `missing_parameter` | 400 | Falta el campo `file`. |
| `invalid_parameter` | 400 | Un campo tiene un tipo incorrecto, se envió un campo desconocido, el modelo no es un modelo de detección de imágenes o la `Idempotency-Key` no es válida. |
| `file_not_found` | 400 | El ID de archivo es desconocido, ha caducado o ya se usó. |
| `unsupported_file`, `invalid_file` | 415, 422 | El archivo no es una imagen JPEG, PNG o WebP, o está dañado. |
| `file_too_large`, `too_many_pixels` | 413 | El archivo multipart supera los 4 MB, el archivo subido supera los 10 MB o la imagen supera los 40 megapíxeles. |
| `unsupported_media_type`, `invalid_json` | 415, 400 | El cuerpo no es `multipart/form-data` ni un objeto JSON. |
| `model_not_found` | 404 | El `model` es desconocido. |
| `insufficient_balance`, `spend_limit_reached` | 402 | El saldo o el límite mensual de la clave no permite cubrir la solicitud. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | La `Idempotency-Key` se usó con un cuerpo distinto, o su primera solicitud sigue en curso. |
| `service_unavailable`, `analysis_failed` | 503, 502 | El servicio de detección no está disponible temporalmente o está ocupado. No se cobra; reintente. `service_unavailable` incluye una cabecera `retry-after`. |

> **Nota.** Envíe `Idempotency-Key` para que, si reintenta tras un tiempo de espera agotado, no se facture dos veces. Consulte [Idempotencia](https://fileverity.com/es/docs/idempotency.md).

