API - Référence de la réponse.

Un appel réussi à POST /api/public/detect retourne HTTP 200 avec un corps JSON décrivant tout ce qui a été trouvé dans votre image ou vidéo. Cette page documente chaque champ.

La forme de la réponse est la même pour les modèles EU et global — seul le vocabulaire des espèces diffère (deepfaune_label_en pour eu, noms communs SpeciesNet pour global).

Exemple de réponse (image)

json

{
  "species": {
    "red deer": 2
  },
  "metadata": {
    "photo_id": "ca947365-cbd7-4651-bfc3-b7a505f99b33",
    "camera_id": "b5fd3fef-7d54-4c14-86d2-699187eb0728"
  },
  "has_human": false,
  "n_animals": 2,
  "n_persons": 0,
  "detections": [
    {
      "box": [0.7787, 0.4361, 0.9992, 0.7783],
      "label": "animal",
      "antlers": "no",
      "species": "red deer",
      "confidence": 0.909
    },
    {
      "box": [0.0594, 0.2822, 0.1589, 0.4604],
      "label": "animal",
      "antlers": "yes",
      "species": "red deer",
      "sex_hint": "likely_male",
      "antler_box": [0.0898, 0.1735, 0.1156, 0.2697],
      "confidence": 0.522
    }
  ],
  "media_type": "image",
  "n_vehicles": 0,
  "needs_review": false
}

Champs de niveau supérieur

Le tableau detections

Chaque élément décrit un objet détecté.

Les détections de personnes et de véhicules comportent une box et un label mais pas de champs species ou de bois.

Boîtes englobantes

Toutes les boîtes — box et antler_box — utilisent le même format : quatre nombres [x1, y1, x2, y2], chacun entre 0 et 1, mesurés depuis le coin supérieur gauche de l'image complète. Cela les rend indépendantes de la résolution, de sorte que la même réponse fonctionne que vous rendiez une miniature ou l'image en taille réelle.

Pour convertir une boîte en pixels afin de dessiner une superposition :

js

const [x1, y1, x2, y2] = det.box;
const left   = x1 * imageWidth;
const top    = y1 * imageHeight;
const width  = (x2 - x1) * imageWidth;
const height = (y2 - y1) * imageHeight;
// draw a rectangle at (left, top) of size width × height

antler_box se dessine exactement de la même manière et, lorsqu'elle est présente, marque l'emplacement des bois.

Champs de bois et de sexe

La détection des bois est volontairement conservatrice, et la réponse reflète cela :

• antlers: "yes" est la seule valeur qui ajoute sex_hint: "likely_male" et une antler_box. Traitez-la comme probable, pas certaine.

• antlers: "uncertain" contribue à needs_review afin que vous puissiez y regarder de plus près.

• antlers: "no" (ou l'absence de champs de bois) n'implique jamais un animal femelle — une biche, des bois tombés ou une tête tournée ou recadrée ne peuvent tout simplement pas être jugés.

Seules les espèces de cervidés pour lesquelles vous activez la vérification des bois porteront ces champs ; tous les autres animaux les omettent.

needs_review

Cet indicateur est true lorsque le résultat contient quelque chose qui mérite un regard humain, généralement :

• un appel de bois "uncertain", ou

• une espèce reconnue qui se trouve en dehors de la liste autorisée que vous avez envoyée dans species (ou vos paramètres de profil par défaut).

Un résultat signalé est toujours retourné en intégralité — needs_review indique simplement à votre application de le router pour confirmation plutôt que de le traiter comme définitif.

Réponses vidéo

Une requête vidéo retourne les mêmes champs de niveau supérieur avec media_type: "video", où les comptes (species, n_animals, …) sont agrégés sur les images échantillonnées, plus des détails supplémentaires au niveau des images (une image clé représentative et une répartition par image). Les champs exacts des images sont documentés séparément — voir l'exemple vidéo dans la documentation.

Statut HTTP

Une réponse 200 contient toujours le JSON ci-dessus. Tout statut non-200 indique un problème (authentification, crédits, validation, etc.) — voir la référence des Erreurs pour la liste complète et comment gérer chacune.