API – Antwort-Referenz.

Ein erfolgreicher Aufruf von POST /api/public/detect gibt HTTP 200 mit einem JSON-Body zurück, der alles beschreibt, was in Ihrem Bild oder Video gefunden wurde. Diese Seite dokumentiert jedes Feld.

Die Antwortstruktur ist für die EU- und globalen Modelle identisch – nur das Artenvokabular unterscheidet sich (deepfaune_label_en für eu, SpeciesNet-Gemeinschaftsnamen für global).

Beispielantwort (Bild)

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
}

Felder der obersten Ebene

Das detections-Array

Jedes Element beschreibt ein erkanntes Objekt.

Personen- und Fahrzeugerkennungen enthalten eine box und ein label, aber keine species- oder Geweihfelder.

Begrenzungsrahmen

Alle Rahmen – box und antler_box – verwenden dasselbe Format: vier Zahlen [x1, y1, x2, y2], jeweils zwischen 0 und 1, gemessen von der oberen linken Ecke des vollständigen Bildes. Dies macht sie auflösungsunabhängig, sodass dieselbe Antwort funktioniert, unabhängig davon, ob Sie ein Miniaturbild oder das Bild in voller Größe rendern.

Um einen Rahmen in Pixel für das Zeichnen einer Überlagerung umzuwandeln:

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 wird genau auf die gleiche Weise gezeichnet und markiert, wenn vorhanden, wo sich das Geweih befindet.

Geweih- und Geschlechtsfelder

Die Geweiherkennung ist absichtlich konservativ, und die Antwort spiegelt dies wider:

• antlers: "yes" ist der einzige Wert, der sex_hint: "likely_male" und eine antler_box hinzufügt. Behandeln Sie es als wahrscheinlich, nicht sicher.

• antlers: "uncertain" trägt zu needs_review bei, damit Sie genauer hinsehen können.

• antlers: "no" (oder das Fehlen von Geweihfeldern) impliziert niemals ein weibliches Tier – eine Hirschkuh, abgeworfenes Geweih oder ein gedrehter oder beschnittener Kopf können einfach nicht beurteilt werden.

Nur die Hirscharten, für die Sie die Geweihprüfung aktivieren, enthalten diese Felder; alle anderen Tiere lassen sie weg.

needs_review

Dieses Flag ist true, wenn das Ergebnis etwas enthält, das einen menschlichen Blick wert ist, typischerweise:

• ein "uncertain" Geweih-Aufruf, oder

• eine erkannte Art, die außerhalb der Zulassungsliste liegt, die Sie in species gesendet haben (oder Ihre Profileinstellungen).

Ein gekennzeichnetes Ergebnis wird weiterhin vollständig zurückgegeben – needs_review teilt Ihrer Anwendung einfach mit, es zur Bestätigung weiterzuleiten, anstatt es als endgültig zu behandeln.

Videoantworten

Eine Videoanfrage gibt dieselben Felder der obersten Ebene mit media_type: "video" zurück, wobei die Zählungen (species, n_animals, …) über die abgetasteten Frames aggregiert werden, plus zusätzliche Details auf Frame-Ebene (ein repräsentatives Schlüsselbild und eine Aufschlüsselung pro Frame). Die genauen Frame-Felder sind separat dokumentiert – siehe das Videobeispiel in der Dokumentation.

HTTP-Status

Eine 200-Antwort enthält immer das oben genannte JSON. Jeder Nicht-200-Status weist auf ein Problem hin (Authentifizierung, Credits, Validierung usw.) – siehe die Fehler-Referenz für die vollständige Liste und wie man mit jedem umgeht.