# 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.

Source : https://fileverity.com/fr/docs/analyses

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](https://fileverity.com/fr/docs/files.md)), 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](https://fileverity.com/fr/api/detection-d-images-ia) et l’[API de détection de fraude documentaire](https://fileverity.com/fr/api/detection-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`. |

**Créer une analyse: cURL**

```bash
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"}}'
```

**Créer une analyse: JavaScript**

```javascript
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();
```

**Créer une analyse: Python**

```python
import os
import uuid
import 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](https://fileverity.com/fr/docs/webhooks.md).

**Interroger jusqu’à la fin: JavaScript**

```javascript
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();
}
```

**Interroger jusqu’à la fin: Python**

```python
import time

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

**202 Accepted, document**

```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.

**Réessayer en cas de saturation: JavaScript**

```javascript
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");
}
```

**Réessayer en cas de saturation: Python**

```python
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é. |

**Analyse échouée**

```json
{
  "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. |

**200 OK, image**

```json
{
  "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. |

**200 OK, document**

```json
{
  "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](https://fileverity.com/fr/docs/api-reference.md#create-analysis).

| 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`.

**Lister et annuler: cURL**

```bash
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`.

**Télécharger le PDF: cURL**

```bash
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é](https://fileverity.com/fr/docs/analyses.md#busy). |
| `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](https://fileverity.com/fr/docs/idempotency.md). |
| `not_cancelable` | 409 | Seuls les documents encore en cours de traitement peuvent être annulés. |

> **Remarque.** 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](https://fileverity.com/fr/docs/errors.md).