Documentation de l’API Fileverity

Analyses

Créez des analyses d’images et de documents, attendez le résultat avec Prefer: wait ou par interrogation, annulez, téléchargez le rapport PDF et lisez l’objet rapport et la page de vérification.

Voir en MarkdownMis à jour le 2026-11-04

Une analyse est une vérification d’image ou de document. Elle vérifie un fichier téléversé avec fvimg-2 (images) ou fvdoc-3 (documents). Téléversez d’abord le fichier (voir Fichiers), puis créez l’analyse.

Pour une présentation du produit avec une requête et une réponse, consultez l’API de détection d’images IA et l’API de détection de fraude documentaire.

Créer une analyse

POST /analyses renvoie l’objet analyse. Le prix est réservé à la création de l’analyse et libéré en cas d’échec ou d’annulation.

Champ	Type	Obligatoire	Description
`model`	chaîne	Oui	`fvimg-2` ou `fvdoc-3`, ou un ID d’instantané tel que `fvimg-2-2026-10-30`.
`file`	chaîne	Oui	ID d’un fichier téléversé.
`metadata`	objet	Non	Jusqu’à 16 paires de chaînes. Clés de 40 caractères au plus, valeurs de 500 au plus. Renvoyées avec l’analyse et dans les webhooks.
`options.password`	chaîne	Non	Mot de passe d’un document chiffré, 256 caractères au plus.
`options.locale`	chaîne	Non	Langue des constats sur le document : `en`, `fr`, `de`, `es`, `zh`, `vi` ou `ar`. Valeur par défaut : `en`.

curl https://api.fileverity.com/v1/analyses \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 0e5f6a64-52c2-4b36-9d0d-6f3d2f4c9a10" \  -d '{"model": "fvdoc-3", "file": "file_Pw3mY6zB8Hk2pQ4vN9sL1xR7", "metadata": {"order_id": "A-10492"}}'

const response = await fetch("https://api.fileverity.com/v1/analyses", {  method: "POST",  headers: {    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,    "Content-Type": "application/json",    "Idempotency-Key": crypto.randomUUID(),  },  body: JSON.stringify({ model: "fvdoc-3", file: file.id, metadata: { order_id: "A-10492" } }),});const analysis = await response.json();

import osimport uuidimport requests response = requests.post(    "https://api.fileverity.com/v1/analyses",    headers={        "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"],        "Idempotency-Key": str(uuid.uuid4()),    },    json={"model": "fvdoc-3", "file": file["id"], "metadata": {"order_id": "A-10492"}},)analysis = response.json()

Attendre, interroger ou utiliser des webhooks

La création renvoie 202 avec status: processing. Vous avez trois façons d’obtenir le résultat :

Attendre. Envoyez Prefer: wait=N, où N peut aller jusqu’à 60 secondes. La requête est maintenue ouverte jusqu’à la fin de l’analyse ou jusqu’à l’écoulement de N secondes. Une analyse terminée renvoie 200 ; sinon, vous obtenez quand même 202. L’en-tête de réponse preference-applied: wait=N confirme l’attente.
Interroger. Appelez GET /analyses/{id} à intervalle de quelques secondes jusqu’à ce que status ne soit plus processing.
Webhook. Abonnez-vous à analysis.completed et analysis.failed, puis récupérez l’analyse à l’arrivée de l’événement. Voir Webhooks.

let analysis = created;while (analysis.status === "processing") {  await new Promise((resolve) => setTimeout(resolve, 3000));  const response = await fetch("https://api.fileverity.com/v1/analyses/" + analysis.id, {    headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },  });  analysis = await response.json();}

import time analysis = createdwhile analysis["status"] == "processing":    time.sleep(3)    analysis = requests.get("https://api.fileverity.com/v1/analyses/" + analysis["id"], headers=headers).json()

{  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "analysis",  "created": 1793700120,  "model": "fvdoc-3-2026-11-03",  "livemode": true,  "status": "processing",  "file": {    "name": "contract.pdf",    "bytes": 18874368,    "format": "pdf"  },  "report_id": null,  "report_url": null,  "summary": null,  "result": null,  "error": null,  "progress": {    "stage": "queued",    "done": 0,    "total": 0,    "position": 1  },  "usage": {    "amount": 599,    "currency": "usd",    "funding": "balance"  },  "metadata": {    "order_id": "A-10492"  },  "completed_at": null,  "expires_at": null}

Tant qu’une analyse est en cours, progress.stage vaut queued, reading, analyzing ou reporting, et position est la position dans la file tant que l’étape est queued. Les documents peuvent être mis en file d’attente. L’attente est facultative pour les documents et peut se terminer avant que le résultat soit prêt : prévoyez donc toujours le cas 202.

Lorsque le service est saturé

Lorsque la capacité est saturée, POST /analyses renvoie 503 avec le code service_unavailable et un en-tête retry-after. Rien ne vous est facturé. Attendez le nombre de secondes indiqué dans retry-after, puis réessayez avec la même Idempotency-Key pour que la nouvelle tentative ne lance jamais une vérification deux fois. Pour un débit optimal, lancez les analyses d’images l’une après l’autre plutôt qu’en parallèle.

async function create(body, key) {  for (let attempt = 0; attempt < 5; attempt++) {    const response = await fetch("https://api.fileverity.com/v1/analyses", {      method: "POST",      headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": key },      body: JSON.stringify(body),    });    if (response.status !== 503) return response;    const wait = Number(response.headers.get("retry-after")) || 15;    await new Promise((resolve) => setTimeout(resolve, wait * 1000));  }  throw new Error("Service busy");}

import time def create(body, key):    for attempt in range(5):        response = requests.post("https://api.fileverity.com/v1/analyses", headers={**headers, "Idempotency-Key": key}, json=body)        if response.status_code != 503:            return response        time.sleep(int(response.headers.get("retry-after", 15)))    raise RuntimeError("Service busy")

Statuts

Statut	Signification
`processing`	L’analyse est en cours. `result` vaut `null`.
`succeeded`	Le résultat est prêt. `report_id`, `report_url`, `summary` et `result` sont renseignés.
`failed`	L’analyse n’a pas pu aboutir. `error` contient le `code` et le `message`. Rien ne vous a été facturé.
`canceled`	Vous l’avez annulée. `error.code` vaut `canceled`. Rien ne vous a été facturé.

{  "id": "an_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "analysis",  "created": 1793700120,  "model": "fvimg-2-2026-10-30",  "livemode": true,  "status": "failed",  "file": {    "name": "claim-photo.jpg",    "bytes": 2481920,    "format": "jpeg"  },  "report_id": null,  "report_url": null,  "summary": null,  "result": null,  "error": {    "code": "analysis_failed",    "message": "The analysis could not be completed. You were not charged; retry it, and contact support with the request ID if it fails again."  },  "progress": null,  "usage": {    "amount": 0,    "currency": "usd",    "funding": null  },  "metadata": null,  "completed_at": 1793700135,  "expires_at": null}

L’objet rapport

Une analyse terminée avec succès contient le même rapport que celui affiché par le site, le PDF et la page de vérification.

Champ	Description
`report_id`	ID de rapport, `FV-XXXX-XXXX-XXXX`.
`report_url`	Page de vérification publique du rapport. Toute personne disposant du lien peut vérifier l’ID de rapport, l’empreinte du fichier et l’horodatage par rapport à l’enregistrement, sans compte.
`summary`	Le verdict synthétique. Voir ci-dessous.
`result.report`	Le rapport complet. `result.report.schema` vaut `fileverity.report/1` pour les images et `fileverity.docpro/1` pour les documents.
`result.stamped_at`	Horodatage Unix correspondant à l’horodatage RFC 3161 émis pour le rapport, ou `null`.
`usage`	`amount` facturé en cents (0 pour les vérifications du démarrage gratuit et les échecs), `currency` et `funding` (`trial` ou `balance`).
`metadata`	Les métadonnées que vous avez envoyées, ou `null`.
`expires_at`	Horodatage Unix après lequel `result` est supprimé. Les résultats sont conservés 7 jours.

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

L’objet report est abrégé ci-dessus ; l’objet réel contient l’ensemble des constats.

Le summary est le verdict stable, lisible par machine. result.report est le rapport complet que le site et le PDF affichent. Sa structure suit le schéma indiqué dans result.report.schema. Au sein d’une même version du schéma, les champs répertoriés conservent leur nom et leur signification, et de nouveaux champs peuvent être ajoutés : ignorez donc les champs que vous ne reconnaissez pas.

Résumé d’image

Champ	Valeurs
`level`	`L0` Indéterminé, `L1` Source vérifiée, `L2` Aucune anomalie constatée, `L3` Examen manuel requis, `L4` Forte suspicion, `L5` Preuves solides contre l’authenticité.
`action`	`accept`, `review`, `reject`, `resubmit`
`assessment`	`authentic_untouched`, `authentic_locally_edited`, `ai_generated`, `undetermined`
`ai`	`labelled`, `very_likely`, `suspected`, `undecided`, `low`, `very_low`, `not_evaluated`
`edit`	`detected`, `suspected`, `suspected_record`, `review`, `generative`, `minor`, `none`, `not_applicable`, `not_evaluated`

Résumé de document

Champ	Description
`kind`	Toujours `docpro`.
`level`	`L0` Indéterminé, `L1` Source vérifiée, `L2` Aucun signe de falsification, `L3` Examen manuel requis, `L4` Risque élevé, `L5` Problèmes établis.
`action`	`accept`, `note` (vérifiez le contenu IA marqué dans le rapport au regard de votre politique), `review`, `reject` ou `resubmit`.
`reason`	Le constat ou la condition à l’origine du niveau, par exemple `clean`, `incomplete` ou un ID de constat, ou `null`.
`findings`	ID des constats importants.
`pages`, `images`	Pages du document et photos intégrées examinées.
`text`	Le verdict sur le texte du document (`ai_generated`, `mixed`, `human`, `inconclusive`), ou `null` si le texte n’a pas été évalué.
`strong`	`true` lorsqu’un constat répertorié est solide. Absent dans les autres cas.

{  "id": "an_Zc4vB7nP1sK8tL3wR6yQm2Xa",  "object": "analysis",  "created": 1793700300,  "model": "fvdoc-3-2026-11-03",  "livemode": true,  "status": "succeeded",  "file": {    "name": "contract.pdf",    "bytes": 18874368,    "format": "pdf"  },  "report_id": "FV-3PXH-6WQ2-8NDC",  "report_url": "https://fileverity.com/verify/FV-3PXH-6WQ2-8NDC",  "summary": {    "kind": "docpro",    "level": "L3",    "action": "review",    "reason": null,    "findings": [],    "pages": 12,    "images": 3,    "text": "human"  },  "result": {    "report": {      "schema": "fileverity.docpro/1",      "id": "FV-3PXH-6WQ2-8NDC"    },    "stamped_at": 1793700340  },  "error": null,  "progress": null,  "usage": {    "amount": 599,    "currency": "usd",    "funding": "balance"  },  "metadata": null,  "completed_at": 1793700341,  "expires_at": 1794305141}

Champs du rapport d’image

result.report d’une analyse d’image. Les objets imbriqués sont répertoriés dans la référence de l’API.

Champ	Type	Obligatoire	Description
`schema`	`"fileverity.report/1"`	Oui
`id`	chaîne	Oui	ID de rapport, FV-XXXX-XXXX-XXXX.
`sample`	`true`	Non	Présent dans les rapports d’exemple fixes renvoyés par les clés de test.
`issuedAt`	chaîne	Non	Date d’émission du rapport, ISO 8601 en UTC. Format : date-time.
`issuer`	objet	Non	Émetteur du rapport.
`file`	objet	Non	L’image vérifiée.
`pro`	objet	Non	Le verdict. Les mêmes valeurs que summary, avec reason.
`score`	entier ou null	Non	Score d’authenticité de 0 à 100 par paliers de 5 : dans quelle mesure les preuves étayent le caractère authentique et non retouché de la prise de vue. null si non évalué.
`confidence`	une valeur parmi `"high"`, `"medium"`, `"low"`	Non	Ce que ce fichier permet à l’analyse d’établir. Une confiance faible tient en général au fichier lui-même, par exemple une faible résolution ou une forte compression.
`questions`	objet	Non	Les trois questions auxquelles le rapport répond.
`generator`	objet ou null	Non	Le générateur d’IA identifié pour l’image, ou null.
`regions`	tableau d’objets	Non	Zones signalées, en pixels de l’image affichée.
`provenance`	objet	Non	Ce que les données propres au fichier indiquent sur son origine.
`digest`	chaîne	Non	Empreinte du contenu du rapport, utilisée par la page de vérification.

Champs du rapport de document

result.report d’une analyse de document.

Champ	Type	Obligatoire	Description
`schema`	`"fileverity.docpro/1"`	Oui
`id`	chaîne	Oui	ID de rapport, FV-XXXX-XXXX-XXXX.
`sample`	`true`	Non	Présent dans les rapports d’exemple fixes renvoyés par les clés de test.
`issuedAt`	chaîne	Non	Date d’émission du rapport, ISO 8601 en UTC. Format : date-time.
`receivedAt`	chaîne	Non	Date de réception du fichier, ISO 8601 en UTC. Format : date-time.
`issuer`	objet	Non	Émetteur du rapport.
`file`	objet	Non	Le document vérifié.
`level`	une valeur parmi `"L0"`, `"L1"`, `"L2"`, `"L3"`, `"L4"`, `"L5"`	Non	Niveau de risque, de L0 à L5.
`action`	une valeur parmi `"accept"`, `"note"`, `"review"`, `"reject"`, `"resubmit"`	Non
`reason`	chaîne ou null	Non	Le constat ou la condition à l’origine du niveau.
`findings`	tableau d’objets	Non	Les constats à l’origine du niveau, chacun avec les pages et les photos intégrées auxquelles il se rapporte.
`text`	objet	Non	Le résultat pour le texte du document.
`images`	tableau d’objets	Non	Les photos et graphiques intégrés, numérotés dans l’ordre du document.
`structure`	objet ou null	Non	L’historique des modifications du fichier, ou null s’il n’a pas été examiné.
`provenance`	objet	Non	Ce que les données propres au fichier indiquent sur son origine.
`digest`	chaîne	Non	Empreinte du contenu du rapport, utilisée par la page de vérification.

Récupérer, lister et annuler

GET /analyses/{id} renvoie l’analyse, avec son résultat tant qu’il est conservé.
GET /analyses liste les analyses de l’espace de travail, les plus récentes d’abord. limit va de 1 à 100 (20 par défaut), type filtre par image ou document, et starting_after prend le next_cursor de la page précédente. Les éléments de la liste n’incluent jamais result.
POST /analyses/{id}/cancel annule une analyse de document encore en cours et libère le montant correspondant. Les analyses d’images ne peuvent pas être annulées ; une annulation tardive ou demandée après la fin de l’analyse renvoie not_cancelable.

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

Rapport PDF

GET /analyses/{id}/report.pdf télécharge le rapport PDF scellé d’une analyse terminée avec succès tant que son résultat est conservé. Ajoutez ?locale= avec en, fr, de, es, zh, vi ou ar (en par défaut). Envoyez l’en-tête Authorization ; la réponse est de type application/pdf.

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

Pour les documents, les images des pages et les extraits de texte sont conservés pendant 3 heures après la vérification. Passé ce délai, le PDF ne les contient plus et l’en-tête de réponse x-evidence-included vaut false. Téléchargez le PDF dès la fin de l’analyse si vous voulez qu’il inclue les preuves.

Erreurs

Code	Statut	Cause
`file_not_found`	400	L’ID de fichier est inconnu, expiré ou déjà utilisé, ou le téléversement vers `upload.url` n’est pas encore terminé.
`model_not_found`	404	Modèle inconnu.
`invalid_parameter`	400	Un champ est manquant, de type incorrect ou inconnu. Les modèles de texte relèvent de `POST /text/detections`.
`unsupported_file`, `invalid_file`	415, 422	Le format du fichier n’est pas pris en charge par le modèle, ou le fichier est endommagé.
`file_too_large`, `too_many_pixels`, `too_many_pages`, `document_too_long`	413	Une limite de taille a été dépassée.
`password_required`, `wrong_password`	422	Le document est chiffré. Envoyez `options.password`.
`not_examinable`	422	Le document ne contient rien qui puisse être examiné. Non facturé.
`insufficient_balance`, `spend_limit_reached`	402	Le solde ou la limite mensuelle de la clé ne suffit pas à couvrir le prix.
`service_unavailable`, `analysis_failed`	503, 502	Panne temporaire ou capacité saturée. Non facturé ; réessayez. `service_unavailable` s’accompagne d’un en-tête `retry-after`. Voir Lorsque le service est saturé.
`unsupported_media_type`	415	Le corps n’est pas envoyé en `application/json`.
`idempotency_mismatch`, `idempotency_in_progress`	409	La `Idempotency-Key` a été utilisée avec un corps différent, ou sa première requête est encore en cours. Voir Idempotence.
`not_cancelable`	409	Seuls les documents encore en cours de traitement peuvent être annulés.

Certains échecs surviennent après la création de l’analyse, par exemple lorsqu’un modèle ne peut pas terminer. Ils renseignent status: failed et error sur l’analyse au lieu de faire échouer l’appel de création, et le webhook analysis.failed est déclenché. Voir Erreurs.