# Análisis

> Cree análisis de imágenes y documentos, espere el resultado con Prefer: wait o con consultas periódicas, cancele, descargue el informe en PDF y lea el objeto de informe y la página de verificación.

Fuente: https://fileverity.com/es/docs/analyses

Un análisis es una comprobación de imagen o de documento. Comprueba un archivo subido con `fvimg-2` (imágenes) o `fvdoc-3` (documentos). Suba primero el archivo (consulte [Archivos](https://fileverity.com/es/docs/files.md)) y luego cree el análisis.

Para ver una descripción general del producto con una solicitud y una respuesta, consulte la [API de detección de imágenes IA](https://fileverity.com/es/api/deteccion-de-imagenes-ia) y la [API de detección de fraude documental](https://fileverity.com/es/api/deteccion-de-fraude-documental).

## Crear un análisis

`POST /analyses` devuelve el objeto de análisis. El precio se reserva al crear el análisis y se libera si falla o se cancela.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `model` | cadena | Sí | `fvimg-2` o `fvdoc-3`, o el ID de una versión fechada, como `fvimg-2-2026-10-30`. |
| `file` | cadena | Sí | ID de un archivo subido. |
| `metadata` | objeto | No | Hasta 16 pares de cadenas. Claves de hasta 40 caracteres y valores de hasta 500. Se devuelven en el análisis y en los webhooks. |
| `options.password` | cadena | No | Contraseña de un documento cifrado, de hasta 256 caracteres. |
| `options.locale` | cadena | No | Idioma de los hallazgos del documento: `en`, `fr`, `de`, `es`, `zh`, `vi` o `ar`. Valor predeterminado: `en`. |

**Crear un análisis: cURL**

```bash
curl https://api.fileverity.com/v1/analyses \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e5f6a64-52c2-4b36-9d0d-6f3d2f4c9a10" \
  -d '{"model": "fvdoc-3", "file": "file_Pw3mY6zB8Hk2pQ4vN9sL1xR7", "metadata": {"order_id": "A-10492"}}'
```

**Crear un análisis: JavaScript**

```javascript
const response = await fetch("https://api.fileverity.com/v1/analyses", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ model: "fvdoc-3", file: file.id, metadata: { order_id: "A-10492" } }),
});
const analysis = await response.json();
```

**Crear un análisis: Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.fileverity.com/v1/analyses",
    headers={
        "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"model": "fvdoc-3", "file": file["id"], "metadata": {"order_id": "A-10492"}},
)
analysis = response.json()
```

## Esperar, consultar periódicamente o usar webhooks

La creación devuelve `202` con `status: processing`. Hay tres formas de obtener el resultado:

- **Esperar.** Envíe `Prefer: wait=N`, donde N es de hasta 60 segundos. La solicitud se mantiene abierta hasta que el análisis termina o pasan N segundos. Un análisis terminado devuelve `200`; si no, sigue devolviendo `202`. El encabezado de respuesta `preference-applied: wait=N` confirma la espera.
- **Consultar periódicamente.** Llame a `GET /analyses/{id}` cada pocos segundos hasta que `status` deje de ser `processing`.
- **Webhook.** Suscríbase a `analysis.completed` y `analysis.failed` y obtenga el análisis cuando llegue el evento. Consulte [Webhooks](https://fileverity.com/es/docs/webhooks.md).

**Consultar periódicamente hasta que termine: JavaScript**

```javascript
let analysis = created;
while (analysis.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  const response = await fetch("https://api.fileverity.com/v1/analyses/" + analysis.id, {
    headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },
  });
  analysis = await response.json();
}
```

**Consultar periódicamente hasta que termine: Python**

```python
import time

analysis = created
while analysis["status"] == "processing":
    time.sleep(3)
    analysis = requests.get("https://api.fileverity.com/v1/analyses/" + analysis["id"], headers=headers).json()
```

**202 Accepted, documento**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvdoc-3-2026-11-03",
  "livemode": true,
  "status": "processing",
  "file": {
    "name": "contract.pdf",
    "bytes": 18874368,
    "format": "pdf"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": null,
  "progress": {
    "stage": "queued",
    "done": 0,
    "total": 0,
    "position": 1
  },
  "usage": {
    "amount": 599,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": {
    "order_id": "A-10492"
  },
  "completed_at": null,
  "expires_at": null
}
```

Mientras un análisis se procesa, `progress.stage` es uno de `queued`, `reading`, `analyzing` o `reporting`, y `position` es la posición en la cola mientras la fase es `queued`. Los documentos pueden quedar en cola. Esperar es opcional para los documentos y la espera puede terminar antes de que el resultado esté listo, así que gestione siempre el `202`.

## Cuando el servicio está ocupado

Cuando la capacidad está ocupada, `POST /analyses` devuelve `503` con el código `service_unavailable` y un encabezado `retry-after`. No se le cobra. Espere el número de segundos indicado en `retry-after` y reintente con la misma `Idempotency-Key`, de modo que el reintento nunca ejecute una comprobación dos veces. Para obtener el mejor rendimiento, ejecute los análisis de imágenes uno tras otro en lugar de en paralelo.

**Reintentar cuando está ocupado: JavaScript**

```javascript
async function create(body, key) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch("https://api.fileverity.com/v1/analyses", {
      method: "POST",
      headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": key },
      body: JSON.stringify(body),
    });
    if (response.status !== 503) return response;
    const wait = Number(response.headers.get("retry-after")) || 15;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error("Service busy");
}
```

**Reintentar cuando está ocupado: Python**

```python
import time

def create(body, key):
    for attempt in range(5):
        response = requests.post("https://api.fileverity.com/v1/analyses", headers={**headers, "Idempotency-Key": key}, json=body)
        if response.status_code != 503:
            return response
        time.sleep(int(response.headers.get("retry-after", 15)))
    raise RuntimeError("Service busy")
```

## Estados

| Estado | Significado |
| --- | --- |
| `processing` | El análisis se está ejecutando. `result` es `null`. |
| `succeeded` | El resultado está listo. `report_id`, `report_url`, `summary` y `result` tienen valor. |
| `failed` | No se pudo completar el análisis. `error` contiene el `code` y el `message`. No se le cobró. |
| `canceled` | Usted lo canceló. `error.code` es `canceled`. No se le cobró. |

**Análisis fallido**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "failed",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": null,
  "report_url": null,
  "summary": null,
  "result": null,
  "error": {
    "code": "analysis_failed",
    "message": "The analysis could not be completed. You were not charged; retry it, and contact support with the request ID if it fails again."
  },
  "progress": null,
  "usage": {
    "amount": 0,
    "currency": "usd",
    "funding": null
  },
  "metadata": null,
  "completed_at": 1793700135,
  "expires_at": null
}
```

## El objeto de informe

Un análisis finalizado correctamente incluye el mismo informe que muestran el sitio web, el PDF y la página de verificación.

| Campo | Descripción |
| --- | --- |
| `report_id` | ID del informe, `FV-XXXX-XXXX-XXXX`. |
| `report_url` | Página de verificación pública del informe. Cualquier persona con el enlace puede cotejar el ID del informe, la huella del archivo y la marca de tiempo con el registro, sin necesidad de una cuenta. |
| `summary` | El veredicto breve. Consulte más abajo. |
| `result.report` | El informe completo. `result.report.schema` es `fileverity.report/1` para imágenes y `fileverity.docpro/1` para documentos. |
| `result.stamped_at` | Marca de tiempo Unix de la marca de tiempo RFC 3161 emitida para el informe, o `null`. |
| `usage` | `amount` cobrado en centavos (0 para las comprobaciones del inicio gratuito y los fallos), `currency` y `funding` (`trial` o `balance`). |
| `metadata` | Los metadatos que envió, o `null`. |
| `expires_at` | Marca de tiempo Unix a partir de la cual se elimina `result`. Los resultados se conservan 7 días. |

**200 OK, imagen**

```json
{
  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "analysis",
  "created": 1793700120,
  "model": "fvimg-2-2026-10-30",
  "livemode": true,
  "status": "succeeded",
  "file": {
    "name": "claim-photo.jpg",
    "bytes": 2481920,
    "format": "jpeg"
  },
  "report_id": "FV-7K2M-9QXD-4T8R",
  "report_url": "https://fileverity.com/verify/FV-7K2M-9QXD-4T8R",
  "summary": {
    "level": "L2",
    "assessment": "authentic_untouched",
    "action": "accept",
    "ai": "very_low",
    "edit": "none"
  },
  "result": {
    "report": {
      "schema": "fileverity.report/1",
      "id": "FV-7K2M-9QXD-4T8R"
    },
    "stamped_at": 1793700130
  },
  "error": null,
  "progress": null,
  "usage": {
    "amount": 199,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": {
    "order_id": "A-10492"
  },
  "completed_at": 1793700131,
  "expires_at": 1794304931
}
```

El objeto `report` se ha abreviado arriba; el real contiene todos los hallazgos.

El `summary` es el veredicto estable y legible por máquinas. `result.report` es el informe completo que muestran el sitio web y el PDF. Su estructura sigue el esquema indicado en `result.report.schema`. Dentro de una misma versión del esquema, los campos documentados mantienen su nombre y su significado, y se pueden añadir campos nuevos, así que ignore los campos que no reconozca.

### Resumen de imagen

| Campo | Valores |
| --- | --- |
| `level` | `L0` Sin determinar, `L1` Origen verificado, `L2` Sin anomalías detectadas, `L3` Requiere revisión manual, `L4` Alta sospecha, `L5` Pruebas sólidas contra la autenticidad. |
| `action` | `accept`, `review`, `reject`, `resubmit` |
| `assessment` | `authentic_untouched`, `authentic_locally_edited`, `ai_generated`, `undetermined` |
| `ai` | `labelled`, `very_likely`, `suspected`, `undecided`, `low`, `very_low`, `not_evaluated` |
| `edit` | `detected`, `suspected`, `suspected_record`, `review`, `generative`, `minor`, `none`, `not_applicable`, `not_evaluated` |

### Resumen de documento

| Campo | Descripción |
| --- | --- |
| `kind` | Siempre `docpro`. |
| `level` | `L0` Sin determinar, `L1` Origen verificado, `L2` Sin indicios de manipulación, `L3` Requiere revisión manual, `L4` Riesgo alto, `L5` Problemas acreditados. |
| `action` | `accept`, `note` (revise el contenido de IA señalado en el informe según su política), `review`, `reject` o `resubmit`. |
| `reason` | El hallazgo o la condición que determina el nivel, por ejemplo `clean`, `incomplete` o un ID de hallazgo, o `null`. |
| `findings` | ID de los hallazgos relevantes. |
| `pages`, `images` | Páginas del documento y fotos incrustadas examinadas. |
| `text` | El veredicto sobre el texto del documento (`ai_generated`, `mixed`, `human`, `inconclusive`), o `null` cuando no se evaluó el texto. |
| `strong` | `true` cuando un hallazgo de los listados es sólido. Ausente en caso contrario. |

**200 OK, documento**

```json
{
  "id": "an_Zc4vB7nP1sK8tL3wR6yQm2Xa",
  "object": "analysis",
  "created": 1793700300,
  "model": "fvdoc-3-2026-11-03",
  "livemode": true,
  "status": "succeeded",
  "file": {
    "name": "contract.pdf",
    "bytes": 18874368,
    "format": "pdf"
  },
  "report_id": "FV-3PXH-6WQ2-8NDC",
  "report_url": "https://fileverity.com/verify/FV-3PXH-6WQ2-8NDC",
  "summary": {
    "kind": "docpro",
    "level": "L3",
    "action": "review",
    "reason": null,
    "findings": [],
    "pages": 12,
    "images": 3,
    "text": "human"
  },
  "result": {
    "report": {
      "schema": "fileverity.docpro/1",
      "id": "FV-3PXH-6WQ2-8NDC"
    },
    "stamped_at": 1793700340
  },
  "error": null,
  "progress": null,
  "usage": {
    "amount": 599,
    "currency": "usd",
    "funding": "balance"
  },
  "metadata": null,
  "completed_at": 1793700341,
  "expires_at": 1794305141
}
```

### Campos del informe de imagen

`result.report` de un análisis de imagen. Los objetos anidados se enumeran en la [referencia de la API](https://fileverity.com/es/docs/api-reference.md#create-analysis).

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `schema` | `"fileverity.report/1"` | Sí |  |
| `id` | cadena | Sí | ID del informe, FV-XXXX-XXXX-XXXX. |
| `sample` | `true` | No | Presente en los informes de ejemplo fijos que devuelven las claves de prueba. |
| `issuedAt` | cadena | No | Cuándo se emitió el informe, en ISO 8601 y UTC. Formato date-time. |
| `issuer` | objeto | No | Quién emitió el informe. |
| `file` | objeto | No | La imagen comprobada. |
| `pro` | objeto | No | El veredicto. Los mismos valores que summary, con reason. |
| `score` | entero o null | No | Puntuación de autenticidad de 0 a 100 en pasos de 5: en qué medida las pruebas respaldan que la imagen es una captura auténtica y sin editar. null cuando no se evaluó. |
| `confidence` | uno de `"high"`, `"medium"`, `"low"` | No | Hasta qué punto este archivo permite que el análisis llegue a conclusiones. Una confianza baja suele deberse al propio archivo, por ejemplo, a una resolución baja o a una compresión intensa. |
| `questions` | objeto | No | Las tres preguntas a las que responde el informe. |
| `generator` | objeto o null | No | El generador de IA identificado para la imagen, o null. |
| `regions` | array de objetos | No | Regiones marcadas, en píxeles de la imagen mostrada. |
| `provenance` | objeto | No | Lo que dicen los propios registros del archivo sobre su origen. |
| `digest` | cadena | No | Huella del contenido del informe, que usa la página de verificación. |

### Campos del informe de documento

`result.report` de un análisis de documento.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `schema` | `"fileverity.docpro/1"` | Sí |  |
| `id` | cadena | Sí | ID del informe, FV-XXXX-XXXX-XXXX. |
| `sample` | `true` | No | Presente en los informes de ejemplo fijos que devuelven las claves de prueba. |
| `issuedAt` | cadena | No | Cuándo se emitió el informe, en ISO 8601 y UTC. Formato date-time. |
| `receivedAt` | cadena | No | Cuándo se recibió el archivo, en ISO 8601 y UTC. Formato date-time. |
| `issuer` | objeto | No | Quién emitió el informe. |
| `file` | objeto | No | El documento comprobado. |
| `level` | uno de `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"` | No | Nivel de riesgo, de L0 a L5. |
| `action` | uno de `"accept"`, `"note"`, `"review"`, `"reject"`, `"resubmit"` | No |  |
| `reason` | cadena o null | No | El hallazgo o la condición que determina el nivel. |
| `findings` | array de objetos | No | Los hallazgos que determinan el nivel, cada uno con las páginas y las fotos incrustadas a las que se refiere. |
| `text` | objeto | No | El resultado para el texto del documento. |
| `images` | array de objetos | No | Las fotos y los gráficos incrustados, numerados en el orden del documento. |
| `structure` | objeto o null | No | El historial de ediciones del archivo, o null si no se examinó. |
| `provenance` | objeto | No | Lo que dicen los propios registros del archivo sobre su origen. |
| `digest` | cadena | No | Huella del contenido del informe, que usa la página de verificación. |

## Recuperar, listar y cancelar

- `GET /analyses/{id}` devuelve el análisis, con su resultado mientras se conserva.
- `GET /analyses` lista los análisis del espacio de trabajo, del más reciente al más antiguo. `limit` va de 1 a 100 (valor predeterminado: 20), `type` filtra por `image` o `document`, y `starting_after` recibe el `next_cursor` de la página anterior. Los elementos de la lista nunca incluyen `result`.
- `POST /analyses/{id}/cancel` cancela un análisis de documento que aún se está procesando y libera su cargo. Los análisis de imagen no se pueden cancelar; una cancelación tardía o sobre un análisis ya terminado devuelve `not_cancelable`.

**Listar y cancelar: cURL**

```bash
curl "https://api.fileverity.com/v1/analyses?limit=20&type=document" \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"

curl -X POST https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/cancel \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

## Informe en PDF

`GET /analyses/{id}/report.pdf` descarga el informe en PDF sellado de un análisis finalizado correctamente mientras se conserva su resultado. Añada `?locale=` con `en`, `fr`, `de`, `es`, `zh`, `vi` o `ar` (valor predeterminado: `en`). Envíe el encabezado `Authorization`; la respuesta es `application/pdf`.

**Descargar el PDF: cURL**

```bash
curl "https://api.fileverity.com/v1/analyses/an_8Hk2pQ4vN9sL1xR7cW3mY6zB/report.pdf?locale=en" \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -o Fileverity-FV-7K2M-9QXD-4T8R.pdf
```

En los documentos, las imágenes de páginas y los extractos de texto se conservan 3 horas después de la comprobación. Pasado ese tiempo, el PDF los omite y el encabezado de respuesta `x-evidence-included` es `false`. Descargue el PDF cuando termine el análisis si necesita que incluya las evidencias.

## Errores

| Código | Estado | Causa |
| --- | --- | --- |
| `file_not_found` | 400 | El ID del archivo es desconocido, ha caducado o ya se usó, o la subida a `upload.url` aún no ha terminado. |
| `model_not_found` | 404 | Modelo desconocido. |
| `invalid_parameter` | 400 | Falta un campo, tiene un tipo incorrecto o es desconocido. Los modelos de texto corresponden a `POST /text/detections`. |
| `unsupported_file`, `invalid_file` | 415, 422 | El formato del archivo no es compatible con el modelo, o el archivo está dañado. |
| `file_too_large`, `too_many_pixels`, `too_many_pages`, `document_too_long` | 413 | Se superó un límite de tamaño. |
| `password_required`, `wrong_password` | 422 | El documento está cifrado. Envíe `options.password`. |
| `not_examinable` | 422 | El documento no tiene nada que se pueda examinar. No se cobra. |
| `insufficient_balance`, `spend_limit_reached` | 402 | El saldo o el límite mensual de la clave no cubre el precio. |
| `service_unavailable`, `analysis_failed` | 503, 502 | Un fallo temporal o capacidad ocupada. No se cobra; reintente. `service_unavailable` incluye un encabezado `retry-after`. Consulte [Cuando el servicio está ocupado](https://fileverity.com/es/docs/analyses.md#busy). |
| `unsupported_media_type` | 415 | El cuerpo no se envía como `application/json`. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | La `Idempotency-Key` se usó con un cuerpo distinto, o su primera solicitud sigue en curso. Consulte [Idempotencia](https://fileverity.com/es/docs/idempotency.md). |
| `not_cancelable` | 409 | Solo se pueden cancelar los documentos que aún se están procesando. |

> **Nota.** Algunos fallos ocurren después de crear el análisis, por ejemplo cuando un modelo no puede terminar. En ese caso establecen `status: failed` y `error` en el análisis en lugar de hacer fallar la llamada de creación, y se envía el webhook `analysis.failed`. Consulte [Errores](https://fileverity.com/es/docs/errors.md).