Documentación de la API de Fileverity

Referencia de la API

Todos los endpoints de la API de Fileverity con sus parámetros, esquemas de solicitud y de respuesta, códigos de error y ejemplos, generados a partir de la especificación OpenAPI 3.1.

Ver como MarkdownActualizado el 2026-11-04

Esta referencia se genera a partir del documento OpenAPI 3.1 de la API, disponible en https://api.fileverity.com/v1/openapi.json, por lo que siempre coincide con la API. Para conceptos y guías, empiece por la Descripción general.

Convenciones

URL base: https://api.fileverity.com/v1. Autentique cada solicitud con Authorization: Bearer <key>. Los errores comparten un único formato, descrito en Errores. Cada respuesta incluye un encabezado x-request-id, y las respuestas autenticadas incluyen los encabezados del límite de frecuencia descritos en Límites de frecuencia y encabezados. Los objetos anidados se abren en secciones desplegables bajo la tabla.

Detecciones de texto

Detectar texto escrito con IA

POST https://api.fileverity.com/v1/text/detections

Clasifica el texto sin formato como escrito con IA, escrito en parte con IA o escrito por una persona, y devuelve los pasajes escritos con IA. El texto se evalúa y se descarta; no se almacena. La facturación cuenta puntos de código Unicode en unidades de 1000 caracteres, redondeadas hacia arriba en cada solicitud. Las solicitudes rechazadas antes de la evaluación no se cobran. Las claves de prueba devuelven sin cargo un resultado fijo de texto escrito por una persona.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`Idempotency-Key`	encabezado	cadena	No	Clave única de hasta 255 caracteres. Repetir la solicitud con la misma clave y el mismo cuerpo en un plazo de 24 horas devuelve la primera respuesta con el encabezado idempotent-replayed: true; la misma clave con un cuerpo distinto devuelve 409.

Cuerpo de la solicitud: application/json, obligatorio

Campo	Tipo	Obligatorio	Descripción
`model`	cadena	No	ID de modelo o ID de versión fechada. Valor predeterminado: `"fvdoc-3-text"`.
`text`	cadena	Sí	Texto sin formato, de al menos 100 palabras y como máximo 100 000 caracteres.
`language`	uno de `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `null`	No	Código ISO 639-1. Se detecta automáticamente si se omite. Valor predeterminado: `null`.

Respuestas

Estado	Descripción	Cuerpo
200	El resultado de la detección.	`TextDetection`
400	Solicitud no válida. Códigos de error: invalid_json, missing_parameter, text_too_short, unsupported_language, invalid_parameter.	`Error`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
402	El saldo o el límite de gasto mensual de la clave no cubre la solicitud. Códigos de error: insufficient_balance, spend_limit_reached.	`Error`
404	Recurso no encontrado. Códigos de error: model_not_found.	`Error`
409	Conflicto con el estado actual. Códigos de error: idempotency_mismatch, idempotency_in_progress.	`Error`
413	Se superó un límite de tamaño. Códigos de error: text_too_long.	`Error`
415	Tipo de medio o formato de archivo no admitido. Códigos de error: unsupported_media_type.	`Error`
429	Demasiadas solicitudes. Códigos de error: rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`
502	No se pudo completar el análisis; no se cobra. Códigos de error: analysis_failed.	`Error`
503	No disponible temporalmente u ocupado; no se cobra. Reintente tras el número de segundos que indica el encabezado retry-after. Códigos de error: service_unavailable.	`Error`

Respuesta 200: TextDetection

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí
`object`	`"text.detection"`	Sí
`created`	entero	Sí	Marca de tiempo Unix.
`model`	cadena	Sí	Versión fechada que produjo el resultado.
`livemode`	booleano	Sí	False con claves de prueba.
`language`	uno de `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`	Sí
`verdict`	uno de `"ai"`, `"mixed"`, `"human"`	Sí	ai: el texto parece escrito con IA en su totalidad; mixed: pasajes escritos con IA dentro de un texto escrito por una persona; human: no se encontró ningún pasaje escrito con IA.
`score`	número	Sí	Puntuación del modelo para el pasaje más parecido a un texto escrito con IA. Mínimo 0. Máximo 1.
`ai_fraction`	número	Sí	Proporción del texto evaluado que está dentro de segmentos escritos con IA. Mínimo 0. Máximo 1.
`segments`	array de objetos	Sí	Pasajes escritos con IA, como posiciones en el texto enviado medidas en puntos de código Unicode. Los límites son aproximados y pueden incluir oraciones adyacentes.
`usage`	objeto	Sí

segments: campos

Campo	Tipo	Obligatorio	Descripción
`start`	entero	Sí
`end`	entero	Sí	Exclusivo.
`score`	número	Sí	Mínimo 0. Máximo 1.

usage: campos

Campo	Tipo	Obligatorio	Descripción
`characters`	entero	Sí	Puntos de código Unicode evaluados.
`free_characters`	entero	Sí	Caracteres cubiertos por su asignación de inicio gratuito; no se facturan.
`billed_units`	entero	Sí	Unidades de 1000 caracteres realmente cobradas, una vez descontados los caracteres gratuitos; billed_units × precio unitario es el coste.

Códigos de error

Código	Estado
`invalid_json`	400
`missing_parameter`	400
`unsupported_media_type`	415
`text_too_short`	400
`text_too_long`	413
`unsupported_language`	400
`model_not_found`	404
`insufficient_balance`	402
`spend_limit_reached`	402
`service_unavailable`	503
`analysis_failed`	502
`invalid_parameter`	400
`idempotency_mismatch`	409
`idempotency_in_progress`	409
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

curl https://api.fileverity.com/v1/text/detections \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -d "$(jq -Rs '{text: .}' essay.txt)"

{  "id": "tdet_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "text.detection",  "created": 1793664000,  "model": "fvdoc-3-text-2026-11-03",  "livemode": true,  "language": "en",  "verdict": "mixed",  "score": 0.97,  "ai_fraction": 0.41,  "segments": [    {      "start": 212,      "end": 433,      "score": 0.97    },    {      "start": 579,      "end": 790,      "score": 0.93    }  ],  "usage": {    "characters": 1412,    "free_characters": 0,    "billed_units": 2  }}

Archivos

Subir un archivo

POST https://api.fileverity.com/v1/files

Sube un archivo para analizarlo. Envíe los archivos de hasta 4 MB como multipart/form-data en el campo file; la respuesta tiene el estado uploaded. Los archivos de más de 4 MB deben subirse con una URL prefirmada. Envíe JSON con filename, content_type y bytes (documentos de hasta 50 MB); la respuesta tiene el estado pending y un objeto upload con una URL prefirmada: envíe a ella los bytes del archivo con PUT y los encabezados indicados antes de que caduque. Un archivo se elimina cuando se inicia un análisis y, como máximo, a las 24 horas. Un espacio de trabajo puede contener a la vez hasta 50 archivos sin caducar y 200 MB por modo.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`Idempotency-Key`	encabezado	cadena	No	Clave única de hasta 255 caracteres. Repetir la solicitud con la misma clave y el mismo cuerpo en un plazo de 24 horas devuelve la primera respuesta con el encabezado idempotent-replayed: true; la misma clave con un cuerpo distinto devuelve 409.

Cuerpo de la solicitud: multipart/form-data, obligatorio

Campo	Tipo	Obligatorio	Descripción
`file`	cadena	Sí	Formato binary.

Cuerpo de la solicitud: application/json, obligatorio

Campo	Tipo	Obligatorio	Descripción
`filename`	cadena	No
`content_type`	cadena	Sí	Tipo MIME del archivo, por ejemplo image/jpeg o application/pdf.
`bytes`	entero	Sí	Tamaño exacto en bytes. Mínimo 1. Máximo 52 428 800.

Respuestas

Estado	Descripción	Cuerpo
201	El archivo.	`File`
400	Solicitud no válida. Códigos de error: invalid_json, missing_parameter, invalid_parameter.	`Error`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
409	Conflicto con el estado actual. Códigos de error: idempotency_mismatch, idempotency_in_progress.	`Error`
413	Se superó un límite de tamaño. Códigos de error: file_too_large.	`Error`
415	Tipo de medio o formato de archivo no admitido. Códigos de error: unsupported_media_type, unsupported_file.	`Error`
422	No se puede procesar el archivo. Códigos de error: invalid_file.	`Error`
429	Demasiadas solicitudes. Códigos de error: pending_files_limit, rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`

Respuesta 201: File

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí
`object`	`"file"`	Sí
`filename`	cadena o null	Sí
`bytes`	entero o null	Sí
`content_type`	cadena	Sí
`status`	uno de `"pending"`, `"uploaded"`	Sí	pending hasta que han llegado los bytes enviados a la URL prefirmada.
`livemode`	booleano	Sí	Los archivos solo son visibles para las claves del mismo modo.
`created`	entero	Sí	Marca de tiempo Unix.
`expires_at`	entero	Sí	Marca de tiempo Unix a partir de la cual se elimina el archivo.
`upload`	objeto	No	Presente en la respuesta a una solicitud de subida en JSON.

upload: campos

Campo	Tipo	Obligatorio	Descripción
`url`	cadena	Sí	Las claves de prueba reciben una URL de marcador de posición (test: true); no se sube ni se almacena nada.
`method`	`"PUT"`	Sí
`headers`	objeto de cadenas	Sí
`expires_at`	entero	Sí	Marca de tiempo Unix.
`test`	`true`	No

Códigos de error

Código	Estado
`invalid_json`	400
`missing_parameter`	400
`unsupported_media_type`	415
`unsupported_file`	415
`invalid_file`	422
`file_too_large`	413
`pending_files_limit`	429
`invalid_parameter`	400
`idempotency_mismatch`	409
`idempotency_in_progress`	409
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

curl https://api.fileverity.com/v1/files \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -F file=@claim-photo.jpg

{  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "file",  "filename": "claim-photo.jpg",  "bytes": 2481920,  "content_type": "image/jpeg",  "status": "uploaded",  "livemode": true,  "created": 1793700000,  "expires_at": 1793786400}

Recuperar un archivo

GET https://api.fileverity.com/v1/files/{id}

Devuelve el archivo y si sus bytes han llegado.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`id`	ruta	cadena	Sí	ID del archivo.

Respuestas

Estado	Descripción	Cuerpo
200	El archivo.	`File`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
404	Recurso no encontrado. Códigos de error: not_found.	`Error`
429	Demasiadas solicitudes. Códigos de error: rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`

Respuesta 200: File

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí
`object`	`"file"`	Sí
`filename`	cadena o null	Sí
`bytes`	entero o null	Sí
`content_type`	cadena	Sí
`status`	uno de `"pending"`, `"uploaded"`	Sí	pending hasta que han llegado los bytes enviados a la URL prefirmada.
`livemode`	booleano	Sí	Los archivos solo son visibles para las claves del mismo modo.
`created`	entero	Sí	Marca de tiempo Unix.
`expires_at`	entero	Sí	Marca de tiempo Unix a partir de la cual se elimina el archivo.
`upload`	objeto	No	Presente en la respuesta a una solicitud de subida en JSON.

upload: campos

Campo	Tipo	Obligatorio	Descripción
`url`	cadena	Sí	Las claves de prueba reciben una URL de marcador de posición (test: true); no se sube ni se almacena nada.
`method`	`"PUT"`	Sí
`headers`	objeto de cadenas	Sí
`expires_at`	entero	Sí	Marca de tiempo Unix.
`test`	`true`	No

Códigos de error

Código	Estado
`not_found`	404
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

curl https://api.fileverity.com/v1/files/file_8Hk2pQ4vN9sL1xR7cW3mY6zB \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "file",  "filename": "claim-photo.jpg",  "bytes": 2481920,  "content_type": "image/jpeg",  "status": "uploaded",  "livemode": true,  "created": 1793700000,  "expires_at": 1793786400}

Eliminar un archivo

DELETE https://api.fileverity.com/v1/files/{id}

Elimina un archivo subido y sus bytes almacenados.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`id`	ruta	cadena	Sí	ID del archivo.

Respuestas

Estado	Descripción	Cuerpo
200	El archivo se eliminó.	`FileDeleted`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
404	Recurso no encontrado. Códigos de error: not_found.	`Error`
429	Demasiadas solicitudes. Códigos de error: rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`

Respuesta 200: FileDeleted

Campo	Tipo	Obligatorio
`id`	cadena	Sí
`object`	`"file"`	Sí
`deleted`	`true`	Sí

Códigos de error

Código	Estado
`not_found`	404
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

curl -X DELETE https://api.fileverity.com/v1/files/file_8Hk2pQ4vN9sL1xR7cW3mY6zB \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "id": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "file",  "deleted": true}

Análisis

Crear un análisis

POST https://api.fileverity.com/v1/analyses

Analiza un archivo subido con fvimg-2 (imágenes) o fvdoc-3 (documentos). Un análisis es una comprobación de imagen o de documento. La respuesta es 202 con el estado processing; el resultado llega por webhook o consultando periódicamente GET /analyses/{id}. Envíe Prefer: wait=N (hasta 60 segundos) para mantener la solicitud abierta hasta que el resultado esté listo; un análisis terminado devuelve 200. El precio se reserva cuando se crea el análisis y se libera si falla o se cancela. Los resultados se conservan 7 días. Cuando la capacidad está ocupada, la API devuelve 503 service_unavailable con un encabezado retry-after y no cobra nada: reintente con la misma Idempotency-Key y ejecute los análisis de imágenes uno tras otro para obtener el mejor rendimiento. Las claves de prueba devuelven un resultado de ejemplo y nunca se cobran; el informe de ejemplo solo contiene unos pocos campos.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`Idempotency-Key`	encabezado	cadena	No	Clave única de hasta 255 caracteres. Repetir la solicitud con la misma clave y el mismo cuerpo en un plazo de 24 horas devuelve la primera respuesta con el encabezado idempotent-replayed: true; la misma clave con un cuerpo distinto devuelve 409.
`Prefer`	encabezado	cadena	No	wait=N mantiene la solicitud abierta hasta N segundos (máximo 60) o hasta que termina el análisis.

Cuerpo de la solicitud: application/json, obligatorio

Campo	Tipo	Obligatorio	Descripción
`model`	uno de `"fvimg-2"`, `"fvimg-2-2026-10-30"`, `"fvdoc-3"`, `"fvdoc-3-2026-11-03"`	Sí	ID de modelo o ID de versión fechada. fvimg-2 analiza imágenes y fvdoc-3, documentos.
`file`	cadena	Sí	ID de un archivo subido.
`metadata`	objeto de cadenas	No	Hasta 16 pares de cadenas (claves de hasta 40 caracteres, valores de hasta 500) que se devuelven en el análisis y en los webhooks.
`options`	objeto	No

options: campos

Campo	Tipo	Obligatorio	Descripción
`password`	cadena	No	Contraseña de un documento cifrado. Longitud máxima 256.
`locale`	uno de `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `"vi"`, `"ar"`	No	Idioma de los hallazgos del documento. Valor predeterminado: `"en"`.

Respuestas

Estado	Descripción	Cuerpo
200	El análisis terminado.	`Analysis`
202	El análisis se está procesando.	`Analysis`
400	Solicitud no válida. Códigos de error: invalid_json, missing_parameter, file_not_found, invalid_parameter.	`Error`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
402	El saldo o el límite de gasto mensual de la clave no cubre la solicitud. Códigos de error: insufficient_balance, spend_limit_reached.	`Error`
404	Recurso no encontrado. Códigos de error: model_not_found.	`Error`
409	Conflicto con el estado actual. Códigos de error: idempotency_mismatch, idempotency_in_progress.	`Error`
413	Se superó un límite de tamaño. Códigos de error: file_too_large, too_many_pixels, too_many_pages, document_too_long.	`Error`
415	Tipo de medio o formato de archivo no admitido. Códigos de error: unsupported_media_type, unsupported_file.	`Error`
422	No se puede procesar el archivo. Códigos de error: invalid_file, password_required, wrong_password, not_examinable.	`Error`
429	Demasiadas solicitudes. Códigos de error: rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`
502	No se pudo completar el análisis; no se cobra. Códigos de error: analysis_failed.	`Error`
503	No disponible temporalmente u ocupado; no se cobra. Reintente tras el número de segundos que indica el encabezado retry-after. Códigos de error: service_unavailable.	`Error`

Respuesta 200: Analysis

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí
`object`	`"analysis"`	Sí
`created`	entero	Sí	Marca de tiempo Unix.
`model`	cadena	Sí	Versión fechada que produjo el resultado.
`livemode`	booleano	Sí
`status`	uno de `"processing"`, `"succeeded"`, `"failed"`, `"canceled"`	Sí
`file`	objeto	Sí
`report_id`	cadena o null	Sí	ID de informe verificable, FV-XXXX-XXXX-XXXX.
`report_url`	cadena o null	Sí	Página de verificación pública del informe.
`summary`	`ImageSummary` o `DocumentSummary` o null	Sí	El veredicto breve y estable: un ImageSummary para imágenes, un DocumentSummary para documentos, null hasta que el análisis termina con éxito.
`result`	objeto o null	Sí	Presente cuando status es succeeded y hasta que caduca el resultado.
`error`	objeto o null	Sí
`progress`	objeto o null	Sí
`usage`	objeto	Sí
`metadata`	objeto o null	Sí
`completed_at`	entero o null	Sí
`expires_at`	entero o null	Sí	Marca de tiempo Unix a partir de la cual se elimina el resultado.

file: campos

Campo	Tipo	Obligatorio
`name`	cadena o null	No
`bytes`	entero o null	No
`format`	cadena o null	No

summary (ImageSummary): campos

Campo	Tipo	Obligatorio	Descripción
`level`	uno de `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"`	Sí	Nivel de riesgo, de L0 a L5.
`assessment`	uno de `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"`	Sí
`action`	uno de `"accept"`, `"review"`, `"reject"`, `"resubmit"`	Sí
`ai`	uno de `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"`	Sí	El hallazgo sobre la generación con IA.
`edit`	uno de `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"`	Sí	El hallazgo sobre la edición local.

summary (DocumentSummary): campos

Campo	Tipo	Obligatorio	Descripción
`kind`	`"docpro"`	Sí
`level`	uno de `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"`	Sí	Nivel de riesgo, de L0 a L5.
`action`	uno de `"accept"`, `"note"`, `"review"`, `"reject"`, `"resubmit"`	Sí	note: revise el contenido de IA señalado en el informe según su política.
`reason`	cadena o null	Sí	El hallazgo o la condición que hay detrás del nivel, por ejemplo clean o incomplete, o un ID de hallazgo.
`findings`	array de cadenas	Sí	ID de los hallazgos relevantes.
`pages`	entero	Sí	Páginas del documento.
`images`	entero	Sí	Fotos incrustadas examinadas.
`text`	uno de `"ai_generated"`, `"mixed"`, `"human"`, `"inconclusive"`, `null`	Sí	El veredicto sobre el texto del documento, o null cuando no se evaluó el texto.
`strong`	`true`	No	Presente cuando un hallazgo de la lista es sólido.

result: campos

Campo	Tipo	Obligatorio	Descripción
`report`	`ImageReport` o `DocumentReport`	No	El informe completo. report.schema es fileverity.report/1 para imágenes y fileverity.docpro/1 para documentos.
`stamped_at`	entero o null	No	Marca de tiempo Unix de la marca de tiempo RFC 3161 emitida para el informe, o null.

report (ImageReport): campos

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.

issuer: campos

Campo	Tipo	Obligatorio	Descripción
`name`	cadena	No
`operator`	cadena	No
`verify`	cadena	No	Página de verificación pública del informe.

file: campos

Campo	Tipo	Obligatorio	Descripción
`name`	cadena o null	No
`sha256`	cadena	No	SHA-256 del archivo comprobado, en hexadecimal.
`bytes`	entero	No
`width`	entero	No	Ancho en píxeles tal como se muestra.
`height`	entero	No	Alto en píxeles tal como se muestra.
`format`	cadena	No

pro: campos

Campo	Tipo	Obligatorio	Descripción
`level`	uno de `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"`	No	Nivel de riesgo, de L0 a L5.
`action`	uno de `"accept"`, `"review"`, `"reject"`, `"resubmit"`	No
`assessment`	uno de `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"`	No
`reason`	cadena o null	No

questions: campos

Campo	Tipo	Obligatorio
`ai`	objeto	No
`edit`	objeto	No
`source`	objeto	No

ai: campos

Campo	Tipo	Obligatorio	Descripción
`key`	uno de `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"`	No
`basis`	uno de `"verified"`, `"detected"`, `"declared"`, `null`	No	En qué se basa la respuesta.
`strength`	uno de `"strong"`, `"moderate"`, `"limited"`, `null`	No	Con qué solidez respalda la evidencia la respuesta.
`likelihood`	entero o null	No	Probabilidad de generación con IA de 0 a 100 en pasos de 5, o null.

edit: campos

Campo	Tipo	Obligatorio	Descripción
`key`	uno de `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"`	No
`basis`	uno de `"verified"`, `"detected"`, `"declared"`, `null`	No	En qué se basa la respuesta.
`strength`	uno de `"strong"`, `"moderate"`, `"limited"`, `null`	No	Con qué solidez respalda la evidencia la respuesta.
`regions`	entero	No	Número de regiones marcadas.

source: campos

Campo	Tipo	Obligatorio	Descripción
`key`	cadena	No
`basis`	uno de `"verified"`, `"detected"`, `"declared"`, `null`	No	En qué se basa la respuesta.
`strength`	uno de `"strong"`, `"moderate"`, `"limited"`, `null`	No	Con qué solidez respalda la evidencia la respuesta.
`signer`	cadena o null	No
`aiClaim`	booleano	No	Indica si los registros del propio archivo declaran que se generó con IA.

generator: campos

Campo	Tipo	Obligatorio	Descripción
`name`	cadena	No
`basis`	cadena	No	Cómo se identificó el generador.

regions: campos

Campo	Tipo	Obligatorio
`id`	cadena	No
`x`	entero	No
`y`	entero	No
`w`	entero	No
`h`	entero	No
`strength`	uno de `"high"`, `"medium"`	No

provenance: campos

Campo	Tipo	Obligatorio	Descripción
`credentials`	uno de `"valid"`, `"unverified"`, `"issues"`, `"invalid"`, `"removed"`, `"none"`	No	Estado de las Credenciales de contenido.
`signer`	cadena o null	No
`software`	array de cadenas	No	Software citado en los registros del archivo.
`camera`	cadena o null	No
`captured`	cadena o null	No	Hora de captura registrada en el archivo, si la hay.

report (DocumentReport): campos

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.

issuer: campos

Campo	Tipo	Obligatorio	Descripción
`name`	cadena	No
`operator`	cadena	No
`verify`	cadena	No	Página de verificación pública del informe.

file: campos

Campo	Tipo	Obligatorio	Descripción
`name`	cadena o null	No
`sha256`	cadena	No	SHA-256 del archivo comprobado, en hexadecimal.
`bytes`	entero	No
`format`	cadena	No
`pages`	entero	No
`textLayer`	uno de `"present"`, `"partial"`, `"absent"`	No	Indica si el documento incluye una capa de texto.

findings: campos

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	No
`basis`	uno de `"verified"`, `"detected"`, `"declared"`	No
`strength`	uno de `"strong"`, `"moderate"`, `"limited"`	No
`material`	booleano	No	Indica si el hallazgo cuenta para el nivel.
`pages`	array de enteros	No
`images`	array de enteros	No

text: campos

Campo	Tipo	Obligatorio	Descripción
`status`	uno de `"evaluated"`, `"insufficient_text"`, `"unsupported_language"`, `"no_text"`	No
`verdict`	uno de `"ai_generated"`, `"mixed"`, `"human"`, `"inconclusive"`	No	Presente cuando status es evaluated.
`words`	entero	No
`languages`	array de cadenas	No
`passages`	entero	No	Número de pasajes señalados.

images: campos

Campo	Tipo	Obligatorio
`n`	entero	No
`pages`	array de enteros	No
`kind`	uno de `"photo"`, `"graphic"`	No
`width`	entero	No
`height`	entero	No
`level`	uno de `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"`, `null`	No
`assessment`	uno de `"authentic_untouched"`, `"authentic_locally_edited"`, `"ai_generated"`, `"undetermined"`, `null`	No
`ai`	uno de `"labelled"`, `"very_likely"`, `"suspected"`, `"undecided"`, `"low"`, `"very_low"`, `"not_evaluated"`, `null`	No
`edit`	uno de `"detected"`, `"suspected"`, `"suspected_record"`, `"review"`, `"generative"`, `"minor"`, `"none"`, `"not_applicable"`, `"not_evaluated"`, `null`	No

structure: campos

Campo	Tipo	Obligatorio
`revisions`	entero o null	No
`changedPages`	array de enteros	No
`addedPages`	entero	No
`signatures`	entero	No

provenance: campos

Campo	Tipo	Obligatorio	Descripción
`credentials`	cadena	No	Estado de las Credenciales de contenido.
`signer`	cadena o null	No
`aiClaim`	booleano	No	Indica si los registros del propio archivo declaran que se generó con IA.
`software`	array de cadenas	No
`created`	cadena o null	No
`modified`	cadena o null	No
`revisions`	entero o null	No
`signed`	booleano o null	No

error: campos

Campo	Tipo	Obligatorio	Descripción
`code`	uno de `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"`	No
`message`	cadena	No

progress: campos

Campo	Tipo	Obligatorio	Descripción
`stage`	uno de `"queued"`, `"reading"`, `"analyzing"`, `"reporting"`	No
`done`	entero	No	Unidades terminadas en la fase actual, cuando se conocen; en caso contrario, 0.
`total`	entero	No	Unidades de la fase actual, cuando se conocen; en caso contrario, 0.
`position`	entero	No	Posición en la cola mientras la fase es queued.

usage: campos

Campo	Tipo	Obligatorio	Descripción
`amount`	entero	No	Cargo en centavos; 0 en las comprobaciones del inicio gratuito y en los fallos.
`currency`	`"usd"`	No
`funding`	uno de `"trial"`, `"balance"`, `null`	No

Códigos de error

Código	Estado
`invalid_json`	400
`missing_parameter`	400
`unsupported_media_type`	415
`model_not_found`	404
`file_not_found`	400
`unsupported_file`	415
`invalid_file`	422
`file_too_large`	413
`too_many_pixels`	413
`too_many_pages`	413
`document_too_long`	413
`password_required`	422
`wrong_password`	422
`not_examinable`	422
`insufficient_balance`	402
`spend_limit_reached`	402
`service_unavailable`	503
`analysis_failed`	502
`invalid_parameter`	400
`idempotency_mismatch`	409
`idempotency_in_progress`	409
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

curl https://api.fileverity.com/v1/analyses \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -H "Prefer: wait=60" \  -d '{"model": "fvimg-2", "file": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB"}'

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

Listar análisis

GET https://api.fileverity.com/v1/analyses

Lista los análisis de imágenes y documentos de su espacio de trabajo, del más reciente al más antiguo. Las claves de prueba siempre reciben una lista vacía.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`limit`	consulta	entero	No	Valor predeterminado: `20`. Mínimo 1. Máximo 100.
`starting_after`	consulta	cadena	No	Cursor: el next_cursor de la página anterior.
`type`	consulta	uno de `"image"`, `"document"`	No

Respuestas

Estado	Descripción	Cuerpo
200	Una página de análisis.	`AnalysisList`
400	Solicitud no válida. Códigos de error: invalid_parameter.	`Error`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
429	Demasiadas solicitudes. Códigos de error: rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`

Respuesta 200: AnalysisList

Campo	Tipo	Obligatorio	Descripción
`object`	`"list"`	Sí
`data`	array de `Analysis`	Sí
`has_more`	booleano	Sí
`next_cursor`	cadena o null	Sí	Páselo como starting_after para obtener la página siguiente.

data: campos

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí
`object`	`"analysis"`	Sí
`created`	entero	Sí	Marca de tiempo Unix.
`model`	cadena	Sí	Versión fechada que produjo el resultado.
`livemode`	booleano	Sí
`status`	uno de `"processing"`, `"succeeded"`, `"failed"`, `"canceled"`	Sí
`file`	objeto	Sí
`report_id`	cadena o null	Sí	ID de informe verificable, FV-XXXX-XXXX-XXXX.
`report_url`	cadena o null	Sí	Página de verificación pública del informe.
`summary`	`ImageSummary` o `DocumentSummary` o null	Sí	El veredicto breve y estable: un ImageSummary para imágenes, un DocumentSummary para documentos, null hasta que el análisis termina con éxito.
`result`	objeto o null	Sí	Presente cuando status es succeeded y hasta que caduca el resultado.
`error`	objeto o null	Sí
`progress`	objeto o null	Sí
`usage`	objeto	Sí
`metadata`	objeto o null	Sí
`completed_at`	entero o null	Sí
`expires_at`	entero o null	Sí	Marca de tiempo Unix a partir de la cual se elimina el resultado.

file: campos

Campo	Tipo	Obligatorio
`name`	cadena o null	No
`bytes`	entero o null	No
`format`	cadena o null	No

result: campos

Campo	Tipo	Obligatorio	Descripción
`report`	`ImageReport` o `DocumentReport`	No	El informe completo. report.schema es fileverity.report/1 para imágenes y fileverity.docpro/1 para documentos.
`stamped_at`	entero o null	No	Marca de tiempo Unix de la marca de tiempo RFC 3161 emitida para el informe, o null.

error: campos

Campo	Tipo	Obligatorio	Descripción
`code`	uno de `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"`	No
`message`	cadena	No

progress: campos

Campo	Tipo	Obligatorio	Descripción
`stage`	uno de `"queued"`, `"reading"`, `"analyzing"`, `"reporting"`	No
`done`	entero	No	Unidades terminadas en la fase actual, cuando se conocen; en caso contrario, 0.
`total`	entero	No	Unidades de la fase actual, cuando se conocen; en caso contrario, 0.
`position`	entero	No	Posición en la cola mientras la fase es queued.

usage: campos

Campo	Tipo	Obligatorio	Descripción
`amount`	entero	No	Cargo en centavos; 0 en las comprobaciones del inicio gratuito y en los fallos.
`currency`	`"usd"`	No
`funding`	uno de `"trial"`, `"balance"`, `null`	No

Códigos de error

Código	Estado
`invalid_parameter`	400
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

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

{  "object": "list",  "data": [    {      "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    }  ],  "has_more": false,  "next_cursor": null}

Recuperar un análisis

GET https://api.fileverity.com/v1/analyses/{id}

Devuelve el análisis, con su resultado una vez que ha terminado con éxito y hasta que caduque.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`id`	ruta	cadena	Sí	ID del análisis.

Respuestas

Estado	Descripción	Cuerpo
200	El análisis.	`Analysis`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
404	Recurso no encontrado. Códigos de error: not_found.	`Error`
429	Demasiadas solicitudes. Códigos de error: rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`

Respuesta 200: Analysis

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí
`object`	`"analysis"`	Sí
`created`	entero	Sí	Marca de tiempo Unix.
`model`	cadena	Sí	Versión fechada que produjo el resultado.
`livemode`	booleano	Sí
`status`	uno de `"processing"`, `"succeeded"`, `"failed"`, `"canceled"`	Sí
`file`	objeto	Sí
`report_id`	cadena o null	Sí	ID de informe verificable, FV-XXXX-XXXX-XXXX.
`report_url`	cadena o null	Sí	Página de verificación pública del informe.
`summary`	`ImageSummary` o `DocumentSummary` o null	Sí	El veredicto breve y estable: un ImageSummary para imágenes, un DocumentSummary para documentos, null hasta que el análisis termina con éxito.
`result`	objeto o null	Sí	Presente cuando status es succeeded y hasta que caduca el resultado.
`error`	objeto o null	Sí
`progress`	objeto o null	Sí
`usage`	objeto	Sí
`metadata`	objeto o null	Sí
`completed_at`	entero o null	Sí
`expires_at`	entero o null	Sí	Marca de tiempo Unix a partir de la cual se elimina el resultado.

file: campos

Campo	Tipo	Obligatorio
`name`	cadena o null	No
`bytes`	entero o null	No
`format`	cadena o null	No

result: campos

Campo	Tipo	Obligatorio	Descripción
`report`	`ImageReport` o `DocumentReport`	No	El informe completo. report.schema es fileverity.report/1 para imágenes y fileverity.docpro/1 para documentos.
`stamped_at`	entero o null	No	Marca de tiempo Unix de la marca de tiempo RFC 3161 emitida para el informe, o null.

error: campos

Campo	Tipo	Obligatorio	Descripción
`code`	uno de `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"`	No
`message`	cadena	No

progress: campos

Campo	Tipo	Obligatorio	Descripción
`stage`	uno de `"queued"`, `"reading"`, `"analyzing"`, `"reporting"`	No
`done`	entero	No	Unidades terminadas en la fase actual, cuando se conocen; en caso contrario, 0.
`total`	entero	No	Unidades de la fase actual, cuando se conocen; en caso contrario, 0.
`position`	entero	No	Posición en la cola mientras la fase es queued.

usage: campos

Campo	Tipo	Obligatorio	Descripción
`amount`	entero	No	Cargo en centavos; 0 en las comprobaciones del inicio gratuito y en los fallos.
`currency`	`"usd"`	No
`funding`	uno de `"trial"`, `"balance"`, `null`	No

Códigos de error

Código	Estado
`not_found`	404
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

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

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

Cancelar un análisis

POST https://api.fileverity.com/v1/analyses/{id}/cancel

Cancela un análisis de documento que aún se está procesando y libera su cargo. Los análisis de imágenes no se pueden cancelar una vez creados.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`id`	ruta	cadena	Sí	ID del análisis.
`Idempotency-Key`	encabezado	cadena	No	Clave única de hasta 255 caracteres. Repetir la solicitud con la misma clave y el mismo cuerpo en un plazo de 24 horas devuelve la primera respuesta con el encabezado idempotent-replayed: true; la misma clave con un cuerpo distinto devuelve 409.

Respuestas

Estado	Descripción	Cuerpo
200	El análisis cancelado.	`Analysis`
400	Solicitud no válida. Códigos de error: invalid_parameter.	`Error`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
404	Recurso no encontrado. Códigos de error: not_found.	`Error`
409	Conflicto con el estado actual. Códigos de error: not_cancelable, idempotency_mismatch, idempotency_in_progress.	`Error`
429	Demasiadas solicitudes. Códigos de error: rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`

Respuesta 200: Analysis

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí
`object`	`"analysis"`	Sí
`created`	entero	Sí	Marca de tiempo Unix.
`model`	cadena	Sí	Versión fechada que produjo el resultado.
`livemode`	booleano	Sí
`status`	uno de `"processing"`, `"succeeded"`, `"failed"`, `"canceled"`	Sí
`file`	objeto	Sí
`report_id`	cadena o null	Sí	ID de informe verificable, FV-XXXX-XXXX-XXXX.
`report_url`	cadena o null	Sí	Página de verificación pública del informe.
`summary`	`ImageSummary` o `DocumentSummary` o null	Sí	El veredicto breve y estable: un ImageSummary para imágenes, un DocumentSummary para documentos, null hasta que el análisis termina con éxito.
`result`	objeto o null	Sí	Presente cuando status es succeeded y hasta que caduca el resultado.
`error`	objeto o null	Sí
`progress`	objeto o null	Sí
`usage`	objeto	Sí
`metadata`	objeto o null	Sí
`completed_at`	entero o null	Sí
`expires_at`	entero o null	Sí	Marca de tiempo Unix a partir de la cual se elimina el resultado.

file: campos

Campo	Tipo	Obligatorio
`name`	cadena o null	No
`bytes`	entero o null	No
`format`	cadena o null	No

result: campos

Campo	Tipo	Obligatorio	Descripción
`report`	`ImageReport` o `DocumentReport`	No	El informe completo. report.schema es fileverity.report/1 para imágenes y fileverity.docpro/1 para documentos.
`stamped_at`	entero o null	No	Marca de tiempo Unix de la marca de tiempo RFC 3161 emitida para el informe, o null.

error: campos

Campo	Tipo	Obligatorio	Descripción
`code`	uno de `"invalid_json"`, `"missing_parameter"`, `"invalid_parameter"`, `"text_too_short"`, `"text_too_long"`, `"unsupported_media_type"`, `"unsupported_language"`, `"file_not_found"`, `"unsupported_file"`, `"file_too_large"`, `"too_many_pixels"`, `"too_many_pages"`, `"document_too_long"`, `"invalid_file"`, `"password_required"`, `"wrong_password"`, `"not_examinable"`, `"missing_api_key"`, `"invalid_api_key"`, `"insufficient_balance"`, `"spend_limit_reached"`, `"not_found"`, `"model_not_found"`, `"not_cancelable"`, `"canceled"`, `"idempotency_mismatch"`, `"idempotency_in_progress"`, `"pending_files_limit"`, `"rate_limited"`, `"internal_error"`, `"analysis_failed"`, `"service_unavailable"`	No
`message`	cadena	No

progress: campos

Campo	Tipo	Obligatorio	Descripción
`stage`	uno de `"queued"`, `"reading"`, `"analyzing"`, `"reporting"`	No
`done`	entero	No	Unidades terminadas en la fase actual, cuando se conocen; en caso contrario, 0.
`total`	entero	No	Unidades de la fase actual, cuando se conocen; en caso contrario, 0.
`position`	entero	No	Posición en la cola mientras la fase es queued.

usage: campos

Campo	Tipo	Obligatorio	Descripción
`amount`	entero	No	Cargo en centavos; 0 en las comprobaciones del inicio gratuito y en los fallos.
`currency`	`"usd"`	No
`funding`	uno de `"trial"`, `"balance"`, `null`	No

Códigos de error

Código	Estado
`not_found`	404
`not_cancelable`	409
`invalid_parameter`	400
`idempotency_mismatch`	409
`idempotency_in_progress`	409
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

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

{  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "analysis",  "created": 1793700120,  "model": "fvimg-2-2026-10-30",  "livemode": true,  "status": "canceled",  "file": {    "name": "claim-photo.jpg",    "bytes": 2481920,    "format": "jpeg"  },  "report_id": null,  "report_url": null,  "summary": null,  "result": null,  "error": {    "code": "canceled",    "message": "The analysis was canceled. You were not charged."  },  "progress": null,  "usage": {    "amount": 0,    "currency": "usd",    "funding": null  },  "metadata": null,  "completed_at": 1793700135,  "expires_at": null}

Descargar el informe en PDF

GET https://api.fileverity.com/v1/analyses/{id}/report.pdf

Devuelve el informe en PDF sellado de un análisis que ha terminado con éxito mientras se conserve su resultado. Las claves de prueba reciben 404. Las evidencias del documento, como las imágenes de páginas, están disponibles durante 3 horas tras el análisis; después el PDF las omite, lo que se indica con x-evidence-included: false.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`id`	ruta	cadena	Sí	ID del análisis.
`locale`	consulta	uno de `"en"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `"vi"`, `"ar"`	No	Valor predeterminado: `"en"`.

Respuestas

Estado	Descripción	Cuerpo
200	El informe en PDF.	Archivo PDF
400	Solicitud no válida. Códigos de error: invalid_parameter.	`Error`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
404	Recurso no encontrado. Códigos de error: not_found.	`Error`
429	Demasiadas solicitudes. Códigos de error: rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`

Códigos de error

Código	Estado
`invalid_parameter`	400
`not_found`	404
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

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

Modelos

Listar modelos

GET https://api.fileverity.com/v1/models

Lista los modelos disponibles para su clave de API.

Respuestas

Estado	Descripción	Cuerpo
200	Los modelos disponibles.	`ModelList`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
429	Demasiadas solicitudes. Códigos de error: rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`

Respuesta 200: ModelList

Campo	Tipo	Obligatorio	Descripción
`object`	`"list"`	Sí
`data`	array de `Model`	Sí

data: campos

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí
`object`	`"model"`	Sí
`created`	entero	Sí	Marca de tiempo Unix de la versión fechada actual.
`owned_by`	cadena	Sí
`name`	cadena	Sí
`type`	uno de `"image"`, `"document"`, `"text"`	Sí
`description`	cadena	Sí
`snapshot`	cadena	Sí	Versión fechada a la que apunta actualmente el ID.
`status`	uno de `"available"`, `"preview"`, `"deprecated"`	Sí
`input`	objeto	Sí	Entrada admitida. En los archivos se indican los formatos y los límites de tamaño; en el texto, los idiomas y los límites de longitud.
`output`	objeto	Sí
`pricing`	objeto	Sí

input: campos

Campo	Tipo	Obligatorio
`formats`	array de cadenas	No
`max_bytes`	entero	No
`max_megapixels`	entero	No
`max_pages`	entero	No
`languages`	array de cadenas	No
`min_words`	entero	No
`max_characters`	entero	No

output: campos

Campo	Tipo	Obligatorio	Descripción
`schema`	cadena	Sí	Esquema del informe en los resultados del análisis.

pricing: campos

Campo	Tipo	Obligatorio	Descripción
`currency`	`"usd"`	Sí
`unit`	cadena	Sí
`unit_amount`	entero	Sí	Precio por unidad en centavos.

Códigos de error

Código	Estado
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

curl https://api.fileverity.com/v1/models \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "object": "list",  "data": [    {      "id": "fvimg-2",      "object": "model",      "created": 1793318400,      "owned_by": "fileverity",      "name": "FVIMG V2",      "type": "image",      "description": "Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.",      "snapshot": "fvimg-2-2026-10-30",      "status": "available",      "input": {        "formats": [          "jpeg",          "png",          "webp"        ],        "max_bytes": 10485760,        "max_megapixels": 40      },      "output": {        "schema": "fileverity.report/1"      },      "pricing": {        "currency": "usd",        "unit": "image",        "unit_amount": 199      }    },    {      "id": "fvdoc-3",      "object": "model",      "created": 1793664000,      "owned_by": "fileverity",      "name": "FVDOC V3",      "type": "document",      "description": "Document fraud analysis. Evaluates AI-written text, embedded photos, edit history and signatures, and returns a verifiable report.",      "snapshot": "fvdoc-3-2026-11-03",      "status": "available",      "input": {        "formats": [          "pdf",          "docx",          "doc",          "rtf",          "odt",          "pptx",          "txt"        ],        "max_bytes": 52428800,        "max_pages": 100      },      "output": {        "schema": "fileverity.docpro/1"      },      "pricing": {        "currency": "usd",        "unit": "document",        "unit_amount": 599      }    },    {      "id": "fvdoc-3-text",      "object": "model",      "created": 1793664000,      "owned_by": "fileverity",      "name": "FVDOC V3 Text",      "type": "text",      "description": "AI-written text detection. Classifies plain text as AI-written, partly AI-written or human-written and marks the AI-written passages.",      "snapshot": "fvdoc-3-text-2026-11-03",      "status": "available",      "input": {        "languages": [          "en",          "fr",          "de",          "es",          "zh"        ],        "min_words": 100,        "max_characters": 100000      },      "output": {        "schema": "fileverity.text-detection/1"      },      "pricing": {        "currency": "usd",        "unit": "1000_characters",        "unit_amount": 14      }    }  ]}

Recuperar un modelo

GET https://api.fileverity.com/v1/models/{model}

Recupera un modelo por su ID o su ID de versión fechada.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`model`	ruta	cadena	Sí	ID de modelo o ID de versión fechada.

Respuestas

Estado	Descripción	Cuerpo
200	El modelo.	`Model`
401	Clave de API ausente o no válida. Códigos de error: missing_api_key, invalid_api_key.	`Error`
404	Recurso no encontrado. Códigos de error: model_not_found.	`Error`
429	Demasiadas solicitudes. Códigos de error: rate_limited.	`Error`
500	Error interno; no se cobra. Códigos de error: internal_error.	`Error`

Respuesta 200: Model

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí
`object`	`"model"`	Sí
`created`	entero	Sí	Marca de tiempo Unix de la versión fechada actual.
`owned_by`	cadena	Sí
`name`	cadena	Sí
`type`	uno de `"image"`, `"document"`, `"text"`	Sí
`description`	cadena	Sí
`snapshot`	cadena	Sí	Versión fechada a la que apunta actualmente el ID.
`status`	uno de `"available"`, `"preview"`, `"deprecated"`	Sí
`input`	objeto	Sí	Entrada admitida. En los archivos se indican los formatos y los límites de tamaño; en el texto, los idiomas y los límites de longitud.
`output`	objeto	Sí
`pricing`	objeto	Sí

input: campos

Campo	Tipo	Obligatorio
`formats`	array de cadenas	No
`max_bytes`	entero	No
`max_megapixels`	entero	No
`max_pages`	entero	No
`languages`	array de cadenas	No
`min_words`	entero	No
`max_characters`	entero	No

output: campos

Campo	Tipo	Obligatorio	Descripción
`schema`	cadena	Sí	Esquema del informe en los resultados del análisis.

pricing: campos

Campo	Tipo	Obligatorio	Descripción
`currency`	`"usd"`	Sí
`unit`	cadena	Sí
`unit_amount`	entero	Sí	Precio por unidad en centavos.

Códigos de error

Código	Estado
`model_not_found`	404
`missing_api_key`	401
`invalid_api_key`	401
`rate_limited`	429
`internal_error`	500

Ejemplo

curl https://api.fileverity.com/v1/models/fvimg-2 \  -H "Authorization: Bearer $FILEVERITY_API_KEY"

{  "id": "fvimg-2",  "object": "model",  "created": 1793318400,  "owned_by": "fileverity",  "name": "FVIMG V2",  "type": "image",  "description": "Image authenticity analysis. Detects AI generation and local edits, checks content credentials and metadata, and returns a verifiable report.",  "snapshot": "fvimg-2-2026-10-30",  "status": "available",  "input": {    "formats": [      "jpeg",      "png",      "webp"    ],    "max_bytes": 10485760,    "max_megapixels": 40  },  "output": {    "schema": "fileverity.report/1"  },  "pricing": {    "currency": "usd",    "unit": "image",    "unit_amount": 199  }}

Eventos de webhook

Fileverity envía estos eventos a sus endpoints de webhook. Las reglas de verificación y de entrega están en Webhooks.

Evento analysis.completed

Se entrega a sus endpoints de webhook conforme a la especificación Standard Webhooks: los encabezados webhook-id, webhook-timestamp y webhook-signature (v1,<base64 HMAC-SHA256 de id.timestamp.body>, con la parte base64 de su secreto whsec_ como clave). Responda con cualquier 2xx en un plazo de 10 segundos; los fallos se reintentan con retroceso exponencial durante 3 días.

Cuerpo de la solicitud: application/json, obligatorio

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí	También se envía como encabezado webhook-id; úselo para descartar los reintentos duplicados.
`object`	`"event"`	Sí
`type`	uno de `"analysis.completed"`, `"analysis.failed"`, `"balance.low"`	Sí
`created`	entero	Sí	Marca de tiempo Unix.
`data`	`Analysis` o `BalanceLow`	Sí	Los eventos analysis.* incluyen el mismo objeto que GET /analyses/{id}, con result siempre null; obtenga el resultado con ese endpoint. Los eventos balance.low incluyen el saldo y el umbral en centavos.

data (BalanceLow): campos

Campo	Tipo	Obligatorio	Descripción
`balance`	entero	Sí	Saldo en centavos.
`threshold`	entero	Sí	Umbral de alerta en centavos.

Evento analysis.failed

Cuerpo de la solicitud: application/json, obligatorio

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí	También se envía como encabezado webhook-id; úselo para descartar los reintentos duplicados.
`object`	`"event"`	Sí
`type`	uno de `"analysis.completed"`, `"analysis.failed"`, `"balance.low"`	Sí
`created`	entero	Sí	Marca de tiempo Unix.
`data`	`Analysis` o `BalanceLow`	Sí	Los eventos analysis.* incluyen el mismo objeto que GET /analyses/{id}, con result siempre null; obtenga el resultado con ese endpoint. Los eventos balance.low incluyen el saldo y el umbral en centavos.

Evento balance.low

Cuerpo de la solicitud: application/json, obligatorio

Campo	Tipo	Obligatorio	Descripción
`id`	cadena	Sí	También se envía como encabezado webhook-id; úselo para descartar los reintentos duplicados.
`object`	`"event"`	Sí
`type`	uno de `"analysis.completed"`, `"analysis.failed"`, `"balance.low"`	Sí
`created`	entero	Sí	Marca de tiempo Unix.
`data`	`Analysis` o `BalanceLow`	Sí	Los eventos analysis.* incluyen el mismo objeto que GET /analyses/{id}, con result siempre null; obtenga el resultado con ese endpoint. Los eventos balance.low incluyen el saldo y el umbral en centavos.

curl https://api.fileverity.com/v1/openapi.json