Cómo elegir una API de detección de IA: diez puntos que comprobar antes de integrarla

Para elegir una API de detección de IA, compruebe diez puntos que deciden si resistirá en producción: qué verifica y qué devuelve, sus límites de entrada, cómo entrega los resultados, si firma los webhooks, si los reintentos son seguros, cómo se comportan los errores y los límites de solicitudes, qué conserva y durante cuánto tiempo, si un resultado puede auditarse y vincularse a una versión del modelo, y cuánto cuesta una comprobación fallida o una prueba. La mayoría de estos puntos se resuelven con la documentación del proveedor, antes de escribir una sola línea de código. El resto requiere un piloto breve.

Esta guía se dirige a desarrolladores y compradores técnicos que conectan un servicio de detección a un flujo de recepción de expedientes, siniestros, altas de clientes o moderación. Evalúa la interfaz, no el detector. Para la precisión, los falsos positivos y la carga de revisión, use la guía para elegir un detector de imágenes IA y la guía sobre precisión. Un detector que rinde bien con sus archivos puede fallar en producción si la API que lo rodea es difícil de reintentar, auditar o pagar.

Cada punto explica por qué importa, cómo comprobarlo en la documentación de cualquier proveedor y qué documenta la API de Fileverity, con enlaces a la documentación de la API. Las mismas diez preguntas sirven para todos los candidatos, y esta guía no nombra ni clasifica a ningún proveedor.

Los diez puntos de un vistazo

La figura muestra dónde se resuelve cada punto. La documentación dice lo que el proveedor promete, una clave de prueba muestra la forma de las solicitudes y las respuestas, y solo un piloto con sus propios archivos revela los tiempos, la eliminación y la facturación.

Alcance y entradas

Modalidad y salida

Por qué importa. «Detección de IA» abarca tareas distintas: saber si una imagen se generó o se editó, si un documento se alteró o contiene pasajes escritos con IA, si un texto sin formato está escrito con IA. Un proveedor que cubre una no cubre necesariamente otra. Una respuesta reducida a un número, sin alcance ni evidencia, es difícil de aprovechar y de defender. Los revisores necesitan saber a qué se refiere un hallazgo, y su código de enrutamiento necesita un campo estable que una máquina pueda leer.

Cómo comprobarlo. Haga una lista de las tareas que necesita y localice cada una por su nombre en la documentación. Abra el esquema de respuesta y busque cuatro cosas: un resumen legible por máquina (veredicto, nivel o acción recomendada) separado de los hallazgos detallados; evidencias que una persona pueda leer; un estado «no evaluable» distinto de «negativo»; y una versión del esquema. Pida respuestas de ejemplo para una alerta, un resultado limpio, un resultado no concluyente y un fallo. La matriz de cobertura de la guía de compra muestra cómo registrar las respuestas.

Qué documenta Fileverity. Tres modelos, cada uno listado con sus límites y su instantánea mediante GET /models: fvimg-2 para imágenes, fvdoc-3 para documentos y fvdoc-3-text para texto sin formato. Las comprobaciones de imagen y de documento devuelven un informe completo con un nivel de resumen y una acción recomendada, los hallazgos detallados, un identificador de informe y un PDF sellado. Las comprobaciones de texto devuelven un resultado con un veredicto (escrito con IA, mixto o escrito por una persona), puntuaciones y los pasajes marcados. La documentación aclara que un resultado de texto es una estimación estadística, no una prueba de autoría, y que por sí solo no debe decidir nada que afecte a una persona. Consulte Descripción general, El objeto de informe y Detecciones de texto, o las páginas API de detección de imágenes IA y API de detección de fraude documental.

Límites de entrada

Por qué importa. Los límites deciden si su flujo real encaja: fotos hechas con el móvil, capturas de pantalla, escaneos, PDF de varias páginas, archivos protegidos con contraseña, textos largos. Un límite que se descubre por primera vez en producción se traduce en solicitudes fallidas y usuarios molestos.

Cómo comprobarlo. Localice los límites de cada modalidad: formatos admitidos, tamaño máximo, píxeles o páginas, longitud del texto e idiomas. Compruebe cómo se suben los archivos grandes (una sola solicitud o una subida con URL prefirmada), si el formato se detecta por el contenido o se da por bueno el nombre del archivo, y qué devuelve cada exceso. Un código de error propio es buena señal; un truncado silencioso o un 400 genérico, no. Envíe después los archivos más grandes, más pequeños y más incómodos que reciba de verdad, por ejemplo la documentación de un parte de siniestro o de una solicitud de crédito.

Qué documenta Fileverity. Archivos lista los formatos y límites de cada modelo, una subida directa multipart y una subida prefirmada para archivos mayores, la detección del formato por el contenido y un código de error por límite. Los documentos cifrados admiten una opción de contraseña (Análisis). La longitud del texto y los idiomas figuran en Detecciones de texto.

Resultados y entrega

Espera del resultado

Por qué importa. Una llamada que tarda segundos en el laboratorio puede tardar más con carga, y su propia plataforma tiene tiempos de espera: funciones serverless, pasarelas, solicitudes de usuarios. Los proveedores responden de dos maneras. Una llamada síncrona devuelve el resultado en la respuesta. Una llamada asíncrona responde enseguida con un estado y usted recoge el resultado después. Una integración escrita para el primer caso que se encuentra con el segundo pierde resultados o bloquea a los usuarios. La figura muestra las tres vías por las que un resultado asíncrono llega a su código.

Cómo comprobarlo. Busque el ciclo de vida de los estados (processing, succeeded, failed, canceled) y, si el proveedor puede mantener abierta la solicitud, el tiempo máximo de espera documentado. Compruebe cómo y con qué frecuencia consultar, qué ocurre cuando la capacidad está saturada, si los trabajos en cola indican su posición y si un trabajo puede cancelarse sin coste. Un 503 con la cabecera Retry-After, definida en la RFC 9110, indica a su código qué hacer. En el piloto, mida el tiempo de extremo a extremo con el volumen previsto para su tipo de archivo más lento. Un modo de prueba que responde al instante no dice nada sobre esto.

Qué documenta Fileverity. Una comprobación de texto es síncrona: el resultado va en la respuesta. Las comprobaciones de imagen y de documento son asíncronas: al crearlas se devuelve 202 con status: processing. Puede mantener abierta la solicitud con una cabecera Prefer: wait, consultar GET /analyses/{id} o suscribirse a un webhook, y conviene gestionar el 202 incluso cuando se espera, porque los documentos pueden quedar en cola. Cuando la capacidad está saturada, la creación devuelve 503 service_unavailable con retry-after y no se cobra. Una comprobación de documento aún en curso puede cancelarse sin coste. Consulte Esperar, consultar periódicamente o usar webhooks y Cuando el servicio está ocupado.

Firma de webhooks

Por qué importa. Un punto de conexión de webhook es una URL pública que acepta solicitudes que modifican los datos de sus expedientes. Sin verificación, cualquiera que la encuentre puede enviar un falso resultado «limpio». Además, la entrega es poco fiable por naturaleza: su servidor se reinicia, de modo que el emisor debe reintentar, lo que genera duplicados y eventos desordenados.

Cómo comprobarlo. Busque un esquema de firma documentado: un secreto por punto de conexión, una firma sobre el cuerpo sin procesar de la solicitud y una marca de tiempo para poder rechazar solicitudes antiguas. La especificación Standard Webhooks es una convención abierta, con las cabeceras webhook-id, webhook-timestamp y webhook-signature y una firma HMAC-SHA256, de modo que las bibliotecas existentes pueden verificarla. Busque también cómo se renuevan los secretos, el calendario de reintentos y cuándo termina, un identificador de evento estable para deduplicar, si la carga contiene el resultado o solo un identificador, cómo se le comunican los fallos (registro de entregas, reenvío, puntos de conexión desactivados) y un evento de prueba que pueda lanzar. En el piloto, haga que su punto de conexión devuelva un error una vez y envíe después un cuerpo manipulado y una marca de tiempo caducada.

Qué documenta Fileverity. Los webhooks siguen Standard Webhooks, con las tres cabeceras y una firma HMAC-SHA256 calculada sobre el identificador del evento, la marca de tiempo y el cuerpo sin procesar. El secreto de firma se muestra una sola vez y puede renovarse; la documentación incluye código de verificación en JavaScript y Python. La entrega es «al menos una vez» y sin garantía de orden, así que deduplique con webhook-id. Las entregas fallidas se reintentan con intervalos crecientes durante varios días, un punto de conexión que falla de forma continuada se desactiva y los propietarios del espacio de trabajo reciben un correo; la Consola lista las entregas recientes y permite reenviar una. Send test entrega un evento de ejemplo firmado. El evento no contiene el resultado: recupérelo con GET /analyses/{id}. Las comprobaciones de texto son síncronas y no envían webhooks, y las claves de prueba nunca envían eventos. Consulte Verificar la firma y Envío y reintentos.

Fiabilidad con reintentos y carga

Idempotencia y reintentos

Por qué importa. La red puede fallar entre su solicitud y la respuesta. Si un reintento puede crear una segunda comprobación, pagará dos veces y quizá abra un expediente duplicado. Si nunca reintenta, perderá trabajo. Una clave de idempotencia permite al proveedor reconocer un reintento y devolver el primer resultado.

Cómo comprobarlo. Busque una cabecera de clave de idempotencia en cada punto de acceso que cree algo o cueste dinero. Lea qué ocurre cuando se reenvía la misma clave (la misma respuesta, marcada como repetida), cuando se reutiliza con otro cuerpo (debe rechazarse, no aceptarse en silencio), mientras la primera solicitud sigue en curso y tras un error, además de cuánto tiempo se conservan las claves y a qué ámbito se aplican. La cabecera se describe en un borrador del IETF que en noviembre de 2026 aún no era una RFC; los proveedores difieren en los detalles, así que pruébelo. En el piloto, envíe dos veces la misma solicitud y corte la conexión a mitad de solicitud; después confirme un resultado y un solo cobro.

Qué documenta Fileverity. Una cabecera Idempotency-Key funciona en cada punto de acceso POST: comprobaciones de texto, subidas de archivos, creación y cancelación de comprobaciones. Una repetición devuelve la respuesta guardada con idempotent-replayed: true, sin ejecutar ni cobrar nada de nuevo. La misma clave con otro cuerpo devuelve 409 idempotency_mismatch, y la misma clave mientras la primera solicitud sigue en curso devuelve 409 idempotency_in_progress. Las respuestas de error no se guardan, de modo que un reintento tras un error vuelve a ejecutar la solicitud. Las claves se limitan al espacio de trabajo, al modo (live o test) y al punto de acceso, y se conservan durante un plazo documentado. Consulte Idempotencia.

Errores e ID de solicitud

Por qué importa. Su código debe decidir qué reintentar, qué corregir, qué mostrar a un usuario y qué enviar al soporte del proveedor. Los mensajes de error escritos en prosa cambian con el tiempo, y el código que los analiza se rompe. Un identificador de solicitud permite que ambas partes encuentren después la misma solicitud.

Cómo comprobarlo. Busque errores con una forma JSON coherente, con un código estable legible por máquina separado del mensaje para personas, una tabla de todos los códigos con su estado HTTP y la pauta de reintento, y un identificador de solicitud en una cabecera de cada respuesta, también en las correctas. Compruebe que la documentación indica si una comprobación fallida se cobra. En el piloto, provoque cada clase de fallo (clave no válida, archivo demasiado grande, formato no admitido, identificador desconocido, saldo vacío) y confirme que el código basta para distinguirlos.

Qué documenta Fileverity. Los errores incluyen type, code, message, param y request_id, y la documentación recomienda decidir según code y no según el mensaje. Cada respuesta lleva una cabecera x-request-id, y la tabla de códigos de error se genera a partir de las propias definiciones de la API. La documentación indica qué errores reintentar y cuáles corregir antes, y una comprobación que termina en error no se cobra. Indique el identificador de solicitud cuando escriba a hello@fileverity.com o use la página de contacto. Consulte Errores.

Límites de solicitudes

Por qué importa. Una ráfaga, como la importación de un atraso o un proceso de fin de mes, puede alcanzar los límites. Sin control, genera fallos y reintentos que empeoran la situación. Los límites también indican cómo espera el proveedor que se le use: repartir la carga y preferir los webhooks a las consultas continuas.

Cómo comprobarlo. Busque el límite por clave o por cuenta y su ventana, cabeceras de respuesta que indiquen el límite, lo que queda y cuándo se reinicia, y una respuesta 429 con cabecera Retry-After (la RFC 6585 define el estado 429). Busque otros topes, como las subidas simultáneas o pendientes, y cómo solicitar límites más altos. Si el modo de prueba del proveedor aplica los mismos límites, lance primero allí una ráfaga.

Qué documenta Fileverity. Cada clave de API tiene un límite por minuto que abarca todos los puntos de acceso, también las solicitudes que devuelven un error. Toda respuesta autenticada lleva x-ratelimit-limit-requests, x-ratelimit-remaining-requests y x-ratelimit-reset-requests, y 429 rate_limited lleva retry-after. Un tope independiente para los archivos subidos que no han caducado devuelve pending_files_limit, sin retry-after. Las claves de prueba y las claves live comparten los límites, así que puede ensayar la espera con una clave de prueba. Los límites más altos se acuerdan con el equipo comercial. Consulte Límites de frecuencia y encabezados.

Datos, evidencias y coste

Conservación de datos

Por qué importa. Los archivos enviados a comprobación suelen contener datos personales o confidenciales: fotos de siniestros, nóminas, contratos. El proveedor pasa a ser encargado del tratamiento de esos datos. Necesita saber qué se guarda, dónde, durante cuánto tiempo, quién accede y si los datos sirven para entrenar modelos.

Cómo comprobarlo. Pida una respuesta por categoría de datos: archivos subidos, texto enviado, datos derivados, resultados, registros y copias de seguridad. «Eliminamos los archivos» no es una respuesta mientras no diga qué se elimina, cuándo y qué permanece. Busque una tabla de conservación en la documentación, un modo de eliminar antes de plazo, las ubicaciones de tratamiento y los subencargados, una declaración sobre el uso para entrenamiento, un acuerdo de tratamiento de datos y una opción de despliegue privado. Si los archivos contienen datos personales, el artículo 28 del RGPD exige elegir únicamente un encargado que ofrezca garantías suficientes y regir el tratamiento por un contrato (RGPD, art. 28 (copia del BOE)); para el tratamiento fuera del Espacio Económico Europeo hace falta además una base para la transferencia. La lista de decisiones de adecuación de la Comisión Europea recoge los países reconocidos, y cada ubicación de tratamiento se valida por separado. La valoración jurídica corresponde a su delegado de protección de datos. En el piloto, confirme que un archivo ha desaparecido tras su comprobación y que los resultados guardados caducan según lo documentado.

Qué documenta Fileverity. Una tabla de conservación, en Conservación de datos y seguridad, cubre cada categoría de datos. Los archivos subidos se eliminan cuando empieza una comprobación y, en todo caso, al cabo de un plazo indicado; DELETE /files/{id} elimina uno antes. El texto enviado se evalúa y se descarta, nunca se guarda. Los resultados de las comprobaciones se conservan durante un tiempo limitado, y los de texto sin el texto. Las pruebas de un documento (imágenes de páginas, extractos) se conservan menos tiempo que el resultado: descargue el informe PDF en cuanto termine la comprobación si quiere que las incluya. Los registros de solicitudes no guardan el cuerpo de las solicitudes ni de las respuestas. Las ubicaciones de tratamiento y los subencargados figuran en la página de seguridad, las condiciones en el acuerdo de tratamiento de datos, y el despliegue privado se ofrece a clientes Enterprise previa solicitud.

Evidencias y versiones del modelo

Por qué importa. Cuando un expediente señalado se impugna meses después, debe poder mostrar qué se comprobó, cuándo, con qué versión de qué modelo y que el archivo no ha cambiado desde entonces. Una simple puntuación en su base de datos no lo logra. Si un proveedor modifica su modelo sin avisar, los resultados sobre un mismo archivo pueden cambiar: ya no podrá comparar un resultado del piloto con producción ni explicar la diferencia entre dos comprobaciones.

Cómo comprobarlo. Busque un identificador estable para cada resultado, que guarde junto al expediente, la huella (hash) del archivo examinado, un sello de tiempo de confianza emitido por una autoridad de sellado (RFC 3161) para que la hora no dependa solo del reloj del proveedor, un informe descargable y un modo de que un tercero lo confirme sin cuenta. Compruebe que cada resultado nombra la versión exacta del modelo, si puede fijar una solicitud a una versión y durante cuánto tiempo sigue disponible, y cómo se anuncian los cambios y las retiradas. La guía sobre sellado de tiempo y hash SHA-256 explica qué demuestra por separado un hash y un sello de tiempo.

Qué documenta Fileverity. Los informes de imagen y de documento llevan un identificador de informe, la huella SHA-256 del archivo examinado, un sello de tiempo RFC 3161 y una página de verificación pública que cualquiera que tenga el enlace puede usar sin cuenta, además de un PDF sellado. Cada resultado nombra la instantánea que lo produjo, un identificador de modelo como fvimg-2 apunta a una instantánea fechada, y pasar el identificador de una instantánea como model fija la solicitud a ella. Los cambios en la v1 son aditivos y constan en el registro de cambios, por lo que los clientes deben ignorar los campos que no conozcan. Los resultados de texto llevan un identificador de detección y la instantánea que los produjo. Los plazos de preaviso para retirar una instantánea pertenecen a su contrato: pídalos por escrito. Consulte El objeto de informe, Convenciones y el Registro de cambios.

Facturación y modo de prueba

Por qué importa. Una lista de precios oculta las reglas que determinan la factura: la unidad facturable, qué ocurre con las comprobaciones fallidas, canceladas o repetidas, el redondeo y lo que puede costar un proceso descontrolado. También necesita poder construir y probar la integración sin gastar dinero ni contaminar los datos de producción.

Cómo comprobarlo. Localice la unidad de facturación de cada modalidad (por imagen, por documento, por bloque de caracteres) y la regla de redondeo. Compruebe si se cobran las solicitudes fallidas, canceladas o rechazadas, si el modelo es de prepago o de suscripción, y si hay límites de gasto, alertas de saldo bajo y un informe de uso que pueda cotejar con sus propios recuentos. Un buen modo de prueba nunca cobra, aplica la misma validación y dice con precisión qué simula y qué no: los tiempos, los webhooks y los resultados reales son las lagunas habituales. En el piloto, coteje el informe de uso del proveedor con su propio registro, incluido un fallo provocado.

Qué documenta Fileverity. La API es de prepago con cargo al saldo del espacio de trabajo, sin suscripción. Los precios se aplican por comprobación de imagen, por comprobación de documento y por bloque de caracteres de texto, redondeado por exceso en cada solicitud. En las comprobaciones de imagen y de documento, el precio se reserva al crearlas y se libera si fallan o se cancelan, y las solicitudes rechazadas antes de evaluarse no se cobran. El inicio gratuito se consume antes que el saldo. Cada clave puede tener un límite de gasto mensual, una alerta de saldo bajo envía un correo y un webhook balance.low, y cada comprobación informa de su cargo en usage. Las claves de prueba nunca cobran ni usan el inicio gratuito, devuelven al instante un ejemplo fijo, aplican la misma validación, los mismos límites de solicitudes y los mismos códigos de error, y no envían webhooks salvo el evento de prueba de la Consola. Los identificadores de informe de ejemplo empiezan por FV-TEST- y no tienen página de verificación pública. Los precios vigentes figuran en Precios y facturación y en la página de la API; el comportamiento de las claves de prueba se describe en Autenticación y claves.

Preguntas frecuentes

¿Conviene una API síncrona o asíncrona?

Ninguna es mejor en sí. Las entradas breves, como un texto sin formato, encajan en una llamada síncrona, y los archivos que requieren un análisis más pesado suelen devolver primero un estado. Lo esencial es que la documentación defina el ciclo de vida, admita la espera, la consulta y los webhooks, y que su código gestione un estado pendiente.

¿Necesito webhooks o basta con consultar?

Para un prototipo o un volumen bajo basta con consultar. Los webhooks ahorran solicitudes y margen de límite, y encajan en producción. En ambos casos, verifique la firma y gestione los duplicados y el estado pendiente.

¿Es estándar la clave de idempotencia?

Es una convención extendida que describe un borrador del IETF que en noviembre de 2026 aún no se había convertido en RFC. Trate el comportamiento exacto como propio de cada proveedor y pruébelo. El de Fileverity se documenta en la página Idempotencia.

¿Una buena API garantiza un detector preciso?

No. Estos puntos se refieren a la integración, no a la calidad de la detección. Evalúe la detección con sus propios archivos, con etiquetas en las que confíe, apoyándose en la guía sobre precisión y en la guía de compra.

¿Puedo probar la API de Fileverity sin pagar?

Sí. Su primer espacio de trabajo incluye un inicio gratuito, y las claves de prueba nunca cobran. Siga el Inicio rápido y consulte Precios y facturación para conocer las condiciones.

Una lista de control para el piloto

Realice el piloto en tres pasadas y conserve un registro fechado de cada respuesta. Primero, una pasada documental: responda los diez puntos con la documentación de cada candidato y descarte las incompatibilidades evidentes antes de escribir código. Después, una pasada con clave de prueba: construya la integración sobre el modo de prueba. Por último, una pasada en condiciones reales: use una clave live con un límite de gasto bajo y una muestra de archivos que esté autorizado a enviar. Para el muestreo, las etiquetas y la puntuación de la calidad de detección en sí, siga el diseño de piloto de Cómo elegir un detector de imágenes IA para empresas.

Guarde las respuestas junto a la matriz de cobertura y la puntuación de la guía de compra. Para empezar con Fileverity, lea la página de la API, las páginas de detección de imágenes y de fraude documental y el Inicio rápido.

Por Yang Zheng · Revisado por Bill Liu