API

API - Referencia de respuesta.

Una llamada exitosa a POST /api/public/detect devuelve HTTP 200 con un cuerpo JSON que describe todo lo encontrado en su imagen o video. Esta página documenta cada campo.

La forma de la respuesta es la misma tanto para los modelos de la UE como para los globales; solo difiere el vocabulario de especies (deepfaune_label_en para eu, nombres comunes de SpeciesNet para global).

Ejemplo de respuesta (imagen)

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
}

Campos de nivel superior

Campo	Tipo	Descripción
`media_type`	string	`"image"` o `"video"`. Le indica qué forma de respuesta esperar.
`species`	object	Un mapa resumen de nombre de especie → recuento, agregado a través de la captura. En el ejemplo, se encontraron dos ciervos rojos, por lo que `{ "red deer": 2 }`. Use esto para obtener un total rápido sin iterar `detections`.
`n_animals`	integer	Número total de animales detectados.
`n_persons`	integer	Número de personas detectadas.
`n_vehicles`	integer	Número de vehículos detectados.
`has_human`	boolean	`true` si se detectó al menos una persona (una bandera de conveniencia igual a `n_persons > 0`). Útil para el manejo de la privacidad.
`needs_review`	boolean	`true` si alguna detección fue incierta o marcada, por ejemplo, una llamada de astas incierta o una especie fuera de su lista de permitidos. No es un error; es una señal para mostrar el resultado para confirmación humana.
`detections`	array	Una entrada por objeto detectado (animal, persona o vehículo). Vea más abajo.
`metadata`	object	Devuelto sin cambios desde su solicitud. Lo que sea que envíe en `metadata` (por ejemplo, `photo_id`, `camera_id`) se devuelve para que pueda correlacionar la respuesta con sus propios registros.

El array `detections`

Cada elemento describe un objeto detectado.

Campo	Tipo	Presente cuando	Descripción
`box`	number[4]	siempre	Cuadro delimitador `[x1, y1, x2, y2]`, normalizado a 0–1, origen superior izquierdo. `(x1, y1)` es la esquina superior izquierda, `(x2, y2)` la inferior derecha, relativa a la imagen completa. Vea Cuadros delimitadores más abajo.
`label`	string	siempre	La categoría de detección: `"animal"`, `"person"` o `"vehicle"`.
`confidence`	number	siempre	Confianza del modelo para esta detección, 0–1. En el ejemplo, el ciervo de pie obtuvo 0.909; el segundo, parcialmente oscurecido, 0.522.
`species`	string	solo animales	La especie reconocida, en el vocabulario del modelo (por ejemplo, `"red deer"`). No presente en detecciones de `person` / `vehicle`.
`antlers`	string	solo ciervos verificados	`"yes"`, `"no"` o `"uncertain"`. Solo presente para las especies de ciervos que habilitó para la verificación de astas.
`sex_hint`	string	`antlers == "yes"`	Siempre `"likely_male"`. Presente solo cuando se detectaron astas claramente.
`antler_box`	number[4]	`antlers == "yes"`	Cuadro delimitador de las astas, mismo formato que `box`. Se encuentra en la cabeza y puede extenderse por encima del `box` del animal.

Las detecciones de personas y vehículos llevan un box y label pero no species ni campos de astas.

Cuadros delimitadores

Todos los cuadros — box y antler_box — usan el mismo formato: cuatro números [x1, y1, x2, y2], cada uno entre 0 y 1, medidos desde la esquina superior izquierda de la imagen completa. Esto los hace independientes de la resolución, por lo que la misma respuesta funciona ya sea que renderice una miniatura o la imagen de tamaño completo.

Para convertir un cuadro a píxeles para dibujar una superposición:

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 dibuja exactamente de la misma manera y, cuando está presente, marca dónde están las astas.

Campos de astas y sexo

La detección de astas es deliberadamente conservadora, y la respuesta refleja eso:

antlers: "yes" es el único valor que agrega sex_hint: "likely_male" y un antler_box. Trátelo como probable, no seguro.
antlers: "uncertain" contribuye a needs_review para que pueda echar un vistazo más de cerca.
antlers: "no" (o la ausencia de campos de astas) nunca implica un animal hembra: una cierva, astas caídas o una cabeza girada o recortada simplemente no se pueden juzgar.

Solo las especies de ciervos que habilite para la verificación de astas llevarán estos campos; todos los demás animales los omiten.

`needs_review`

Esta bandera es true cuando el resultado contiene algo que vale la pena una mirada humana, típicamente:

una llamada de astas "uncertain", o
una especie reconocida que queda fuera de la lista de permitidos que envió en species (o sus valores predeterminados de perfil).

Un resultado marcado aún se devuelve completo — needs_review simplemente le dice a su aplicación que lo enrute para confirmación en lugar de tratarlo como final.

Respuestas de video

Una solicitud de video devuelve los mismos campos de nivel superior con media_type: "video", donde los recuentos (species, n_animals, …) se agregan a través de los fotogramas muestreados, más detalles adicionales a nivel de fotograma (un fotograma clave representativo y un desglose por fotograma). Los campos exactos de fotograma están documentados por separado; consulte el ejemplo de video en la documentación.

Estado HTTP

Una respuesta 200 siempre lleva el JSON anterior. Cualquier estado no 200 indica un problema (autenticación, créditos, validación, etc.); consulte la referencia de Errores para obtener la lista completa y cómo manejar cada uno.

25 vistas

¿Te resultó útil este artículo?