Autenticación y claves

Cada solicitud necesita una clave de API, enviada como token Bearer en el encabezado Authorization.

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

const response = await fetch("https://api.fileverity.com/v1/models", {  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },});

import osimport requests requests.get("https://api.fileverity.com/v1/models", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]})

Las claves son secretos. Llame a la API desde su servidor, guarde las claves en variables de entorno o en un gestor de secretos y no las incluya nunca en el código del navegador ni en aplicaciones móviles.

Claves Live y Test#

Una clave empieza por fv_live_ o fv_test_ y va seguida de 40 letras y dígitos. El prefijo determina el modo.

Ambos modos comparten un único espacio de trabajo. Usan los mismos endpoints, la misma validación, los mismos límites de frecuencia y los mismos códigos de error, así que puede desarrollar con una clave de prueba y cambiar de clave para pasar a producción.

Comportamiento del modo de prueba#

• Detecciones de texto. La solicitud se valida igual que una solicitud Live: siguen aplicándose las comprobaciones de longitud mínima, longitud máxima e idioma. La respuesta es un resultado human fijo, con score y ai_fraction de 0 y sin segments. usage se calcula a partir de su texto. No se cobra ni se registra nada.
• Archivos. Las subidas se validan, pero los bytes no se almacenan, y una solicitud de subida JSON devuelve un objeto de subida de prueba en lugar de una URL prefirmada real (upload.test es true), con el archivo ya uploaded. Los archivos están separados por modo: una clave de prueba no puede leer archivos Live y una clave Live no puede leer archivos de prueba.
• Crear un análisis. Devuelve 200 de inmediato con status: succeeded, un ejemplo fijo con nivel L2 y acción accept, y livemode: false. El ID del análisis empieza por an_test y es el mismo para el mismo archivo. El ID del informe empieza por FV-TEST- y no tiene página de verificación pública. El informe de ejemplo solo contiene los campos del ejemplo.
• Recuperar un análisis. Funciona solo con los ID de análisis de ejemplo. Listar análisis siempre devuelve una lista vacía, cancelar devuelve not_cancelable y no hay PDF de ejemplo. Las claves de prueba no pueden leer análisis Live ni PDF de informes Live.

{  "id": "tdet_Qm4vB7nP1sK8tL3wR6yZ2cXa",  "object": "text.detection",  "created": 1793664000,  "model": "fvdoc-3-text-2026-11-03",  "livemode": false,  "language": "en",  "verdict": "human",  "score": 0,  "ai_fraction": 0,  "segments": [],  "usage": {    "characters": 1412,    "free_characters": 0,    "billed_units": 2  }}

Crear y revocar claves#

Gestione las claves en la Consola, en Claves de API.

• Crear. Ponga un nombre a la clave y elija su modo. La clave completa se muestra una sola vez. Fileverity solo almacena un hash SHA-256 y los últimos cuatro caracteres, así que una clave perdida no se puede recuperar; cree una nueva.
• Límite. Un espacio de trabajo puede tener hasta 20 claves activas. Si se supera ese número, la creación de una clave falla con key_limit.
• Último uso. La Consola muestra cuándo se usó cada clave por última vez.
• Revocar. Las solicitudes que usen una clave revocada fallan de inmediato con invalid_api_key.
• Miembros que se van. Cuando un miembro sale del espacio de trabajo o se le quita, se revocan las claves que creó. Cree las claves de producción desde una cuenta que permanezca en el espacio de trabajo.

Si se filtra una clave#

1. Cree una clave nueva.
2. Actualice su software para que la use.
3. Revoque la clave anterior.

Límites de gasto mensuales#

Cada clave puede tener su propio límite de gasto mensual, en dólares estadounidenses enteros. Solo los propietarios y administradores del espacio de trabajo pueden fijarlo o cambiarlo, al crear la clave o más tarde con Editar límite. Una clave sin límite solo tiene como tope su saldo.

• El límite cuenta lo que la clave ha gastado en el mes calendario en curso, en UTC, y se reinicia el día 1.
• Una solicitud que haría que la clave superase su límite se rechaza con spend_limit_reached (HTTP 402) antes de que empiece cualquier trabajo, y no se cobra.
• Las comprobaciones del inicio gratuito no cuestan nada y no cuentan. Las comprobaciones fallidas y canceladas no se cobran y no cuentan.
• Los límites se aplican a las claves Live. Las claves de prueba nunca gastan.

Use una clave distinta, con su propio límite, para cada servicio o entorno. Así, un proceso descontrolado no puede gastar más que el límite de esa clave.

Errores de autenticación#

Consulte Errores para ver la lista completa.