Documentación de la API de Fileverity

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.

Ver como MarkdownActualizado el 2026-11-04

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) 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 y la API de detección 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`.

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"}}'

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();

import osimport uuidimport 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.

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();}

import time analysis = createdwhile analysis["status"] == "processing":    time.sleep(3)    analysis = requests.get("https://api.fileverity.com/v1/analyses/" + analysis["id"], headers=headers).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.

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");}

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

{  "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.

{  "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.

{  "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.

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.

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.

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.
`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.
`not_cancelable`	409	Solo se pueden cancelar los documentos que aún se están procesando.

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.