Documentation de l’API Fileverity

Fichiers

Téléversez des images et des documents vers Fileverity : multipart pour les fichiers jusqu’à 4 Mo, téléversement par URL présignée jusqu’à 50 Mo. Objet fichier, limites et conservation.

Voir en MarkdownMis à jour le 2026-11-04

Les images et les documents sont vérifiés en deux étapes. Vous téléversez d’abord le fichier avec POST /files et recevez un ID de fichier. Vous créez ensuite une analyse qui fait référence à cet ID. Le texte n’a pas besoin de fichier : utilisez les Détections de texte.

Fichiers pris en charge

	Images (fvimg-2)	Documents (fvdoc-3)
Formats	`jpeg`, `png`, `webp`	`pdf`, `docx`, `doc`, `rtf`, `odt`, `pptx`, `txt`
Taille maximale	10 Mo	50 Mo
Autres limites	40 mégapixels	100 pages

Deux façons de téléverser

Méthode	Requête	Taille	Statut du fichier dans la réponse
Multipart	`multipart/form-data` avec le champ `file`	Jusqu’à 4 Mo	`uploaded`
URL présignée	JSON avec `filename`, `content_type` et `bytes`, puis un `PUT` des octets	Jusqu’à 50 Mo	`pending` jusqu’à l’arrivée des octets

Les images sont limitées à la taille d’image indiquée ci-dessus, quelle que soit la méthode utilisée.

Téléversement multipart

Envoyez les fichiers de 4 Mo maximum en multipart/form-data, dans le champ file. Le format est détecté à partir du contenu du fichier, et non de son nom ou de son type déclaré.

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

import { readFile } from "node:fs/promises"; const form = new FormData();form.append("file", new Blob([await readFile("claim-photo.jpg")]), "claim-photo.jpg");const response = await fetch("https://api.fileverity.com/v1/files", {  method: "POST",  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },  body: form,});const file = await response.json();

import osimport requests response = requests.post(    "https://api.fileverity.com/v1/files",    headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]},    files={"file": open("claim-photo.jpg", "rb")},)file = response.json()

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

Téléversement par URL présignée

Pour les fichiers de plus de 4 Mo, jusqu’à 50 Mo, demandez une URL de téléversement, puis envoyez les octets directement au stockage.

POST /files avec un corps JSON : filename (facultatif), content_type et la taille exacte en bytes. La réponse contient status: pending et un objet upload.
Envoyez par PUT les octets du fichier à upload.url avec les en-têtes de upload.headers, avant upload.expires_at. Aucun en-tête Authorization n’est nécessaire pour cette requête.
Si vous le souhaitez, interrogez GET /files/{id} jusqu’à ce que status soit uploaded.
Créez l’analyse avec l’ID du fichier.

FILE=$(curl -s https://api.fileverity.com/v1/files \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -d '{"filename": "contract.pdf", "content_type": "application/pdf", "bytes": 18874368}') UPLOAD_URL=$(echo "$FILE" | jq -r .upload.url)FILE_ID=$(echo "$FILE" | jq -r .id) curl -X PUT "$UPLOAD_URL" \  -H "content-type: application/pdf" \  --data-binary @contract.pdf

import { readFile } from "node:fs/promises"; const bytes = await readFile("contract.pdf");const response = await fetch("https://api.fileverity.com/v1/files", {  method: "POST",  headers: {    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,    "Content-Type": "application/json",  },  body: JSON.stringify({ filename: "contract.pdf", content_type: "application/pdf", bytes: bytes.length }),});const file = await response.json(); await fetch(file.upload.url, { method: "PUT", headers: file.upload.headers, body: bytes });

import osimport requests data = open("contract.pdf", "rb").read()response = requests.post(    "https://api.fileverity.com/v1/files",    headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]},    json={"filename": "contract.pdf", "content_type": "application/pdf", "bytes": len(data)},)file = response.json() requests.put(file["upload"]["url"], headers=file["upload"]["headers"], data=data)

{  "id": "file_Pw3mY6zB8Hk2pQ4vN9sL1xR7",  "object": "file",  "filename": "contract.pdf",  "bytes": 18874368,  "content_type": "application/pdf",  "status": "pending",  "livemode": true,  "created": 1793700000,  "expires_at": 1793786400,  "upload": {    "url": "https://example.private.blob.vercel-storage.com/f/0d6f1c2e-7b1a-4c53-9a0e-5e8a41b3c7d2?signature=...",    "method": "PUT",    "headers": {      "content-type": "application/pdf"    },    "expires_at": 1793703600  }}

L’URL affichée est raccourcie. Utilisez telle quelle celle de votre réponse. Envoyez l’en-tête content-type exactement comme il est renvoyé dans upload.headers.

Types de contenu acceptés

Catégorie	Types de contenu
Images	`image/jpeg`, `image/png`, `image/webp`
Documents	`application/pdf`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/msword`, `application/rtf`, `application/vnd.oasis.opendocument.text`, `application/vnd.openxmlformats-officedocument.presentationml.presentation`, `text/plain`

L’objet fichier

Champ	Type	Description
`id`	chaîne	ID de fichier, avec le préfixe `file_`.
`object`	chaîne	Toujours `file`.
`filename`	chaîne ou null	Nom de fichier nettoyé.
`bytes`	entier ou null	Taille en octets.
`content_type`	chaîne	Type de contenu détecté ou déclaré.
`status`	chaîne	`pending` jusqu’à l’arrivée des octets téléversés, puis `uploaded`.
`livemode`	booléen	`false` pour les fichiers créés avec une clé de test. Les fichiers sont séparés par mode.
`created`	entier	Horodatage Unix.
`expires_at`	entier	Horodatage Unix après lequel le fichier est supprimé.
`upload`	objet	Présent uniquement dans la réponse à une requête de téléversement JSON : `url`, `method` (`PUT`), `headers` et `expires_at`.

Conservation

Un fichier est conservé 24 heures au plus (voir expires_at), puis supprimé.
Un fichier est supprimé dès qu’une analyse démarre à partir de celui-ci. Chaque fichier téléversé sert à une seule analyse ; téléversez-le à nouveau pour le vérifier de nouveau.
DELETE /files/{id} supprime un fichier et ses octets stockés avant l’échéance.
Un espace de travail peut contenir au plus 50 fichiers non expirés et 200 Mo par mode à la fois. Au-delà, les téléversements échouent avec pending_files_limit (HTTP 429, sans retry-after) jusqu’à ce que des fichiers soient utilisés, supprimés ou expirés.
Un ID de fichier inconnu, expiré ou déjà utilisé renvoie file_not_found lorsque vous créez une analyse, et not_found lorsque vous le récupérez ou le supprimez. file_not_found est aussi renvoyé lorsque le téléversement vers upload.url n’est pas encore terminé : attendez donc que GET /files/{id} indique uploaded.

Erreurs

Code	Statut	Cause
`missing_parameter`	400	Aucun champ `file` dans le corps multipart.
`unsupported_media_type`	415	Le corps n’est ni en `multipart/form-data` ni en JSON.
`unsupported_file`	415	Le format n’est pas pris en charge.
`invalid_file`	422	Le fichier est vide, endommagé ou illisible.
`file_too_large`	413	Un fichier multipart de plus de 4 Mo, ou `bytes` supérieur à 50 Mo.
`invalid_parameter`	400	Un champ JSON est absent, d’un type incorrect ou inconnu.
`invalid_json`	400	Le corps JSON n’est pas un objet.
`pending_files_limit`	429	Trop de téléversements non expirés dans l’espace de travail. La réponse n’est pas accompagnée d’un en-tête `retry-after`.
`idempotency_mismatch`, `idempotency_in_progress`	409	La `Idempotency-Key` a été utilisée avec une autre requête, ou sa première requête est encore en cours.

Les clés de test valident les téléversements mais ne conservent pas les octets. Une requête de téléversement JSON avec une clé de test renvoie un objet de téléversement de test (upload.test vaut true, le fichier est déjà uploaded) : il n’y a rien à envoyer par PUT.