Documentación de la API de Fileverity
Inicio rápido
Cree un espacio de trabajo, genere una clave de API y ejecute sus primeras comprobaciones de texto e imagen con cURL, fetch de JavaScript o requests de Python.
Esta página le lleva desde el registro hasta sus primeros resultados. Necesita una cuenta de Fileverity, una terminal con curl y jq y, para el ejemplo de imagen, un archivo JPEG, PNG o WebP.
1. Abrir la Consola
Inicie sesión en fileverity.com/console con un código enviado por correo o con Google. Su primer inicio de sesión crea un espacio de trabajo personal con su propio saldo de prepago.
Su primer espacio de trabajo empieza con 5 comprobaciones gratuitas de imágenes o documentos y 5000 caracteres de texto gratuitos. No hace falta tarjeta. Hay un inicio gratuito por persona y un número limitado por dominio de correo de empresa. Sus compañeros deben unirse mediante invitación. El inicio gratuito se usa antes que su saldo. Consulte Precios y facturación.
2. Crear una clave de API
Abra Claves de API, elija Crear clave, póngale un nombre y elija un modo. Cree primero una clave Test: devuelve resultados de ejemplo fijos, nunca llama a un modelo y nunca se cobra. La clave completa se muestra una sola vez, así que cópiela ahora.
Mantenga la clave fuera del control de versiones y del código del navegador. Expórtela como variable de entorno:
export FILEVERITY_API_KEY=fv_test_...3. Verificar la clave
GET /models funciona con cualquier clave válida y nunca se cobra. Una respuesta 200 que enumera los modelos indica que la clave es correcta. Un 401 indica que falta la clave, está mal escrita o ha sido revocada.
curl -i 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 },});console.log(response.status);import osimport requests response = requests.get("https://api.fileverity.com/v1/models", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]})print(response.status_code)4. Comprobar un texto
Envíe texto sin formato de al menos 100 palabras a POST /text/detections. Los ejemplos leen el texto de un archivo, así que guarde antes cualquier pasaje de 100 palabras o más como essay.txt. Este comando escribe un ejemplo:
cat > essay.txt <<'EOF'Honestly, the delivery was a mess. The driver turned up at six in the evening,the pallet was wet on one side, and nobody at the depot would pick up thephone until Monday. I photographed everything before signing, which is theonly reason we have a leg to stand on. In today's fast-paced logisticslandscape, it is essential for businesses to prioritize reliable deliveryperformance, as timely and undamaged shipments play a pivotal role infostering customer trust and long-term satisfaction. We lost two days. Martarebuilt the schedule by hand and the Leeds order still went out late. Movingforward, it is crucial to implement robust quality assurance measures andestablish clear communication channels, ensuring that all stakeholders remainaligned and that potential issues are proactively addressed. For now I amasking for a credit note and a named contact. Not another apology.EOFcurl https://api.fileverity.com/v1/text/detections \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -Rs '{text: .}' essay.txt)"import { readFile } from "node:fs/promises"; const response = await fetch("https://api.fileverity.com/v1/text/detections", { method: "POST", headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ text: await readFile("essay.txt", "utf8") }),});const detection = await response.json();if (!response.ok) throw new Error(detection.error.code + ": " + detection.error.message);console.log(detection.verdict, detection.ai_fraction);import osimport requests response = requests.post( "https://api.fileverity.com/v1/text/detections", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]}, json={"text": open("essay.txt", encoding="utf-8").read()},)detection = response.json()if not response.ok: raise RuntimeError(detection["error"]["code"] + ": " + detection["error"]["message"])print(detection["verdict"], detection["ai_fraction"])Con una clave de prueba, la respuesta es un resultado fijo para un texto escrito por una persona. Con una clave Live tiene este aspecto:
{ "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 }}Encontrará los detalles, incluido cómo funcionan las posiciones, en Detecciones de texto.
5. Comprobar una imagen
Las imágenes y los documentos requieren dos llamadas: suba el archivo y, después, cree un análisis que haga referencia a él. Un análisis es una comprobación de imagen o de documento. Prefer: wait=60 mantiene la solicitud abierta hasta que el resultado esté listo, hasta 60 segundos.
FILE_ID=$(curl -s https://api.fileverity.com/v1/files \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -F file=@photo.jpg | jq -r .id) 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_ID\"}"import { readFile } from "node:fs/promises"; const headers = { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY }; const form = new FormData();form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");const file = await (await fetch("https://api.fileverity.com/v1/files", { method: "POST", headers, body: form })).json(); const response = await fetch("https://api.fileverity.com/v1/analyses", { method: "POST", headers: { ...headers, "Content-Type": "application/json", Prefer: "wait=60" }, body: JSON.stringify({ model: "fvimg-2", file: file.id }),});const analysis = await response.json();console.log(analysis.status, analysis.summary, analysis.report_url);import osimport requests headers = {"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]} file = requests.post("https://api.fileverity.com/v1/files", headers=headers, files={"file": open("photo.jpg", "rb")}).json() response = requests.post( "https://api.fileverity.com/v1/analyses", headers={**headers, "Prefer": "wait=60"}, json={"model": "fvimg-2", "file": file["id"]},)analysis = response.json()print(analysis["status"], analysis["summary"], analysis["report_url"])Un análisis terminado devuelve 200 con status: succeeded, un summary breve y el result.report completo. Si la espera se agota antes, recibe 202 con status: processing; consúltelo más tarde con GET /analyses/{id} o reciba un webhook. Consulte Análisis.
{ "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}Con una clave de prueba, el archivo se valida pero no se almacena, y el análisis devuelve de inmediato un ejemplo fijo. Su ID de informe empieza por FV-TEST- y no tiene página de verificación pública.
6. Pasar a producción
- Cree una clave Live en la Consola y úsela en lugar de la clave de prueba. El mismo código funciona sin cambios.
- Use el inicio gratuito o añada fondos al saldo de su espacio de trabajo en Saldo. La recarga mínima es de 19 US$.
- Fije un límite de gasto mensual en la clave y añada un endpoint de webhook en lugar de consultar la API de forma periódica.
- Envíe
Idempotency-Keyen las solicitudes POST para que un reintento nunca ejecute una comprobación dos veces. Consulte Idempotencia.
Para saber qué examina cada comprobación y dónde la usan los equipos, consulte la API de detección de imágenes IA y la API de detección de fraude documental.
Siguiente: Código de ejemplo incluye programas completos en Node.js y Python para cada comprobación y para los webhooks. Después lea Autenticación y claves, Errores y la referencia de la API. Si algo no funciona, escriba a hello@fileverity.com o use la página de contacto, e incluya el ID de solicitud del encabezado x-request-id.