# Détections d’images

> Détectez si une image entière a été générée par IA avec POST /images/detections. Un seul appel synchrone : champs de la requête et de la réponse, valeurs de la réponse, limites et facturation.

Source : https://fileverity.com/fr/docs/image-detections

`POST /images/detections` lance la détection d’images IA. Elle indique si une image entière a été générée par IA avec `vereye-2-detect`, à partir des mêmes modèles, Content Credentials, étiquettes IA et filigranes que le rapport de vérification d’image (`vereye-2`) : les deux donnent donc la même réponse sur la génération par IA. L’appel est synchrone : le résultat est dans la réponse.

Elle n’examine pas les retouches locales, y compris les retouches par IA d’une partie de la photo, et ne renvoie ni identifiant de rapport ni PDF. Pour les retouches, la provenance et un enregistrement que chacun peut vérifier, créez une [analyse](https://fileverity.com/fr/docs/analyses.md) avec `vereye-2`.

**Requête: cURL**

```bash
curl https://api.fileverity.com/v1/images/detections \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Idempotency-Key: 6b9d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e11" \
  -F file=@photo.jpg
```

**Requête: JavaScript**

```javascript
import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const form = new FormData();
form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");

const response = await fetch("https://api.fileverity.com/v1/images/detections", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Idempotency-Key": randomUUID() },
  body: form,
});
const detection = await response.json();
console.log(detection.verdict, detection.ai);
```

**Requête: Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.fileverity.com/v1/images/detections",
    headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    files={"file": open("photo.jpg", "rb")},
)
detection = response.json()
print(detection["verdict"], detection["ai"])
```

## Corps de la requête

Envoyez l’image en `multipart/form-data` dans le champ `file`, jusqu’à 4 Mo. Pour les images plus lourdes, jusqu’à 10 Mo, téléversez-les d’abord avec [`POST /files`](https://fileverity.com/fr/docs/files.md), puis envoyez du JSON :

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `file` | fichier ou chaîne | Oui | L’image, dans une requête multipart, ou l’ID d’une image téléversée, dans une requête JSON. JPEG, PNG, WEBP, jusqu’à 40 mégapixels. L’ID d’un fichier est consommé par la vérification. |
| `model` | chaîne | Non | Valeur par défaut : `vereye-2-detect`. Accepte l’ID du modèle ou son ID d’instantané `vereye-2-detect-2026-10-30`. |

Les champs inconnus sont rejetés avec `invalid_parameter`.

## Réponse

**200 OK**

```json
{
  "id": "idet_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "image.detection",
  "created": 1794096000,
  "model": "vereye-2-detect-2026-10-30",
  "livemode": true,
  "verdict": "ai_generated",
  "ai": {
    "key": "very_likely",
    "basis": "detected",
    "strength": "strong",
    "likelihood": 100
  },
  "generator": null,
  "signals": [
    {
      "id": "model_1",
      "state": "ai"
    },
    {
      "id": "model_2",
      "state": "ai"
    },
    {
      "id": "credentials",
      "state": "none"
    },
    {
      "id": "watermark",
      "state": "none"
    },
    {
      "id": "label",
      "state": "none"
    },
    {
      "id": "tool_data",
      "state": "none"
    },
    {
      "id": "camera",
      "state": "none"
    }
  ],
  "regions": [
    {
      "x": 0,
      "y": 0,
      "w": 576,
      "h": 512,
      "level": 3
    },
    {
      "x": 576,
      "y": 0,
      "w": 384,
      "h": 512,
      "level": 3
    },
    {
      "x": 960,
      "y": 0,
      "w": 576,
      "h": 512,
      "level": 2
    },
    {
      "x": 0,
      "y": 512,
      "w": 576,
      "h": 512,
      "level": 3
    },
    {
      "x": 576,
      "y": 512,
      "w": 384,
      "h": 512,
      "level": 3
    },
    {
      "x": 960,
      "y": 512,
      "w": 576,
      "h": 512,
      "level": 3
    }
  ],
  "candidates": [
    {
      "name": "Midjourney",
      "score": 0.65
    },
    {
      "name": "OpenAI",
      "score": 0.25
    }
  ],
  "quality": {
    "overall": "fair",
    "resolution": "good",
    "compression": "fair",
    "metadata": "fair",
    "distribution": "good"
  },
  "limits": [
    "no_metadata"
  ],
  "image": {
    "width": 1536,
    "height": 1024,
    "format": "jpeg",
    "jpeg_quality": 85
  },
  "usage": {
    "credits": 4
  }
}
```

| Champ | Type | Description |
| --- | --- | --- |
| `id` | chaîne | ID de détection, avec le préfixe `idet_`. |
| `object` | chaîne | Toujours `image.detection`. |
| `created` | entier | Horodatage Unix. |
| `model` | chaîne | Instantané qui a produit le résultat. |
| `livemode` | booléen | `false` pour les clés de test. |
| `verdict` | chaîne | `ai_generated` : l’image a été générée par IA. `no_ai_signs` : rien n’indique une génération par IA. `inconclusive` : les preuves ne permettent pas de trancher. |
| `ai` | objet | La réponse sur la génération par IA, avec les mêmes valeurs que `questions.ai` dans le [rapport d’image](https://fileverity.com/fr/docs/analyses.md#report-image). |
| `generator` | objet ou null | Le générateur déclaré par le fichier via les Content Credentials, les métadonnées ou un filigrane, avec `name` et `basis`. `null` si le fichier n’en nomme aucun. |
| `signals` | tableau | Les vérifications qui fondent la réponse, chacune avec `id` et `state`. Voir [Signaux](#signals). |
| `regions` | tableau ou null | Une grille grossière posée sur l’image. Chaque cellule porte `x`, `y`, `w` et `h` en pixels de l’image affichée, et un `level` de 0 à 3 pour l’intensité des indices de génération. `null` lorsque l’image est trop petite pour une grille. |
| `candidates` | tableau | Jusqu’à trois familles de générateurs dont les traits de pixels sont les plus proches de ceux de l’image, chacune avec `name` et un `score` de 0 à 1. Vide sauf si le verdict est `ai_generated`. |
| `quality` | objet ou null | Dans quelle mesure le fichier se prête à l’analyse : `overall`, `resolution`, `compression`, `metadata` et `distribution`, chacun valant `good`, `fair` ou `poor`. |
| `limits` | tableau | Ce qui limite le résultat : `low_resolution`, `heavy_compression`, `platform_copy`, `no_metadata` ou `models_disagree`. |
| `image` | objet | `width` et `height` tels qu’affichés, `format`, et `jpeg_quality`, la qualité JPEG estimée ou `null`. |
| `usage` | objet | `credits` débités. |

## Lire la réponse

| `ai.key` | `verdict` | Signification |
| --- | --- | --- |
| `labelled` | `ai_generated` | Des Content Credentials, une étiquette IA ou un filigrane déclarent une génération par IA. `ai.basis` vaut `verified` pour des justificatifs de confiance, sinon `declared` ou `detected`. |
| `very_likely`, `suspected` | `ai_generated` | Les pixels indiquent une génération par IA, de façon marquée ou avec quelques divergences. |
| `undecided` | `inconclusive` | Les signaux sont faibles ou se contredisent. |
| `low`, `very_low` | `no_ai_signs` | Rien dans les pixels ni dans les métadonnées n’indique une génération par IA. |

`ai.strength` vaut `strong`, `moderate` ou `limited` et indique dans quelle mesure les preuves étayent la réponse. `ai.likelihood` va de 0 à 100 par pas de 5, et vaut `null` pour `labelled`.

> **Remarque.** `no_ai_signs` ne prouve pas qu’une photo est authentique ou non retouchée. La détection d’images IA ne cherche pas les retouches. Quand une décision en dépend, lancez un rapport de vérification d’image et faites examiner le résultat par une personne.

## Signaux

`signals` énumère chaque vérification effectuée, pour que vous voyiez sur quoi repose la réponse. Un `state` à `ai` indique une génération par IA.

| `id` | `state` | Vérification |
| --- | --- | --- |
| `model_1`, `model_2` | `ai`, `unclear`, `clear`, `unavailable` | Deux modèles entraînés indépendamment qui analysent les pixels. |
| `credentials` | `ai`, `ai_unverified`, `other`, `none` | Content Credentials (C2PA). `ai_unverified` : les Content Credentials déclarent une génération par IA, mais leur émetteur n’a pas pu être vérifié. `other` : des Content Credentials sont présents et ne déclarent aucune génération par IA. |
| `watermark` | `ai`, `none`, `unavailable` | Filigranes invisibles que les outils de génération open source intègrent dans les pixels. |
| `label` | `ai`, `none` | Une déclaration de génération par IA dans les métadonnées, par exemple le type de source numérique IPTC. |
| `tool_data` | `ai`, `none` | Prompts, paramètres ou noms de générateurs enregistrés dans le fichier. |
| `camera` | `present`, `none` | Marque, modèle et données d’exposition de l’appareil photo. Ces données sont modifiables et ce point d’accès ne les vérifie pas. |

`regions` montre où les indices de génération sont les plus marqués. Les cellules de niveau 3 portent des indices forts. Lorsque le verdict est `no_ai_signs` et que certaines cellules sont au niveau 3, une partie de l’image a pu être générée ou retouchée avec l’IA : ce point d’accès n’examine pas les retouches locales, lancez donc un rapport de vérification d’image.

> **Remarque.** `candidates` est une indication, pas une identification. Il classe les familles de générateurs selon la proximité de leurs traits de pixels avec ceux de l’image, et un générateur absent de l’ensemble de référence apparaît sous la forme de son plus proche voisin. Fiez-vous à `generator` lorsque le fichier nomme lui-même l’outil.

## Facturation

- La détection d’images IA coûte 4 crédits par image.
- Un rapport de vérification d’image de la même image dans le même espace de travail dans un délai de 7 jours coûte 36 crédits au lieu de 40 : les crédits de la détection s’y imputent une seule fois. L’analyse indique le montant débité dans `usage.credits`.
- Les requêtes rejetées avant l’évaluation ne sont pas facturées : paramètres invalides, fichiers non pris en charge ou endommagés, dépassements de taille et cas similaires. Une vérification qui échoue au sein du service (`service_unavailable`, `analysis_failed`) est libérée et n’est pas facturée.
- Un nombre de crédits insuffisant renvoie `insufficient_balance` (402).

## Ce qui est conservé

L’image est examinée puis supprimée. Fileverity conserve le résultat sans l’image (verdict, réponse, générateur, signaux, régions, candidats, qualité, dimensions, empreinte SHA-256 du fichier et utilisation) pendant 7 jours, afin que la Console puisse l’afficher et que l’utilisation puisse être facturée et auditée. Une nouvelle tentative avec la même `Idempotency-Key` reçoit le résultat enregistré pendant 24 heures. Les détections d’images sont synchrones : elles n’apparaissent pas dans `GET /analyses` et n’envoient pas d’événements webhook. Les clés de test n’enregistrent rien. Voir [Conservation des données et sécurité](https://fileverity.com/fr/docs/security.md).

## Erreurs

| Code | Statut | Cause |
| --- | --- | --- |
| `missing_parameter` | 400 | Le champ `file` est manquant. |
| `invalid_parameter` | 400 | Un champ a un type incorrect, un champ inconnu a été envoyé, le modèle n’est pas un modèle de détection d’images, ou l’`Idempotency-Key` est invalide. |
| `file_not_found` | 400 | L’ID du fichier est inconnu, expiré ou déjà utilisé. |
| `unsupported_file`, `invalid_file` | 415, 422 | Le fichier n’est pas une image JPEG, PNG ou WebP, ou il est endommagé. |
| `file_too_large`, `too_many_pixels` | 413 | Le fichier multipart dépasse 4 Mo, le fichier téléversé dépasse 10 Mo, ou l’image dépasse 40 mégapixels. |
| `unsupported_media_type`, `invalid_json` | 415, 400 | Le corps n’est ni du `multipart/form-data` ni un objet JSON. |
| `model_not_found` | 404 | Le `model` est inconnu. |
| `insufficient_balance`, `spend_limit_reached` | 402 | Le solde ou la limite mensuelle de la clé ne permet pas de couvrir la requête. |
| `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. |
| `service_unavailable`, `analysis_failed` | 503, 502 | Le service de détection est temporairement indisponible ou surchargé. Aucune facturation ; réessayez. `service_unavailable` s’accompagne d’un en-tête `retry-after`. |

> **Remarque.** Envoyez une `Idempotency-Key` pour qu’une nouvelle tentative après un délai dépassé ne soit pas facturée deux fois. Voir [Idempotence](https://fileverity.com/fr/docs/idempotency.md).

