A successful call to POST /api/public/detect returns HTTP 200 with a JSON body describing everything found in your image or video. This page documents every field.

The response shape is the same for both the EU and global models — only the species vocabulary differs (deepfaune_label_en for eu, SpeciesNet common names for global).

Example response (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
}

Top-level fields

The detections array

Each element describes one detected object.

Person and vehicle detections carry a box and label but no species or antler fields.

Bounding boxes

All boxes — box and antler_box — use the same format: four numbers [x1, y1, x2, y2], each between 0 and 1, measured from the top-left of the full image. This makes them resolution-independent, so the same response works whether you render a thumbnail or the full-size image.

To convert a box to pixels for drawing an overlay:

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 is drawn exactly the same way and, when present, marks where the antlers are.

Antler and sex fields

Antler detection is deliberately conservative, and the response reflects that:

• antlers: "yes" is the only value that adds sex_hint: "likely_male" and an antler_box. Treat it as likely, not certain.

• antlers: "uncertain" contributes to needs_review so you can take a closer look.

• antlers: "no" (or the absence of antler fields) never implies a female animal — a doe, cast antlers, or a turned or cropped head simply can't be judged.

Only the deer species you enable for antler checking will carry these fields; all other animals omit them.

needs_review

This flag is true when the result contains something worth a human glance, typically:

• an "uncertain" antler call, or

• a recognised species that falls outside the allow-list you sent in species (or your profile defaults).

A flagged result is still returned in full — needs_review simply tells your application to route it for confirmation rather than treat it as final.

Video responses

A video request returns the same top-level fields with media_type: "video", where the counts (species, n_animals, …) are aggregated across the sampled frames, plus additional frame-level detail (a representative key frame and a per-frame breakdown). The exact frame fields are documented separately — see the video example in the docs.

HTTP status

A 200 response always carries the JSON above. Any non-200 status indicates a problem (authentication, credits, validation, etc.) — see the Errors reference for the full list and how to handle each.

Species mapping: DeepFaune and SpeciesNet keys

When you filter results with the species or priors parameter — or when you read a detection back — the species keys come from the recognition model's own vocabulary, not free text. The two models name things differently:

• EU model → DeepFaune labels (deepfaune_label_en)

• Global model → SpeciesNet keys (speciesnet_key)

Below is a mapping for the most common game animals TrailCamHub supports. A "—" in the DeepFaune column means the species has no dedicated European label: the global model recognises it, while in Europe it may be read as a near relative or flagged for review. The level after each SpeciesNet key (species, genus or family) shows how precisely the animal is matched.

Need a species that isn't listed?

These are the animals TrailCamHub maps; the models themselves recognise many more. For the complete vocabularies, consult the models directly: DeepFaune (Europe) at deepfaune.cnrs.fr, and SpeciesNet (worldwide) in the model card on Kaggle or Google's project on GitHub. If you omit the species parameter, you don't need any of these keys — we fall back to your region plus your profile favourites automatically.

Each detection call draws from your TrailCamHub credit balance — the same balance you use across the app.

What a call costs

• Image: 1 credit

• Video: 10 credits

When credits are charged — on submit
Credits are deducted the moment a request is submitted, not when it succeeds. You're paying for the analysis to run, not for a particular result.

Because of that:

• A call still costs credits even when nothing is found — no animals detected, or no antlers on a checked deer. An empty result is still a result; the analysis ran.

• Since the charge is taken at submission, a request that's accepted but then can't be completed (for example a URL we can't reach, or a video with no readable frames) is also charged. Make sure your image and video URLs are public and valid before sending.

• Requests that are rejected before processing — a missing or invalid API key, a malformed body, or an empty balance — are not charged.

What happens at zero balance
If your balance can't cover a call, the request is rejected with HTTP 402 and isn't processed (and isn't charged). Top up to continue.

Checking your balance and buying credits
There's no API endpoint for your balance. Your current credits are shown in the TrailCamHub app, and that's also where you buy more — the same credit packs used across the platform. Plan your usage around the rates above (1 per image, 10 per video, charged up front), since you can't poll the balance programmatically.

What happens if I don't pass the optional parameters?

Only the media URL is required — exactly one of image_url or video_url. Everything else in the body (region_id, model, species, priors, latitude, longitude, country) is an optional override.

When you leave a parameter out, the API falls back to the defaults of the account the API key belongs to — the same settings you configured in TrailCamHub. So a bare request is analysed exactly as it would be inside your own account.

Specifically, when omitted:

• region_id / model → your account's default region, and that region's model (eu or global).

• species → the species list for that region plus your profile favourites — i.e. your allow-list.

• priors → the species you marked as "most likely" in your profile.

• latitude / longitude / country (global model only) → the location configured for your region.

That means the simplest possible call still works and behaves sensibly:

json

{ "image_url": "https://example.com/photo.jpg" }

Overrides are per-call. Any parameter you do send overrides the default for that single request only — it never changes your saved profile. Pass model, species or coordinates when a specific camera or location differs from your defaults; leave them out to use your account settings.

Tip: if all your requests share the same region and species, set them up once in your TrailCamHub profile and send minimal requests. If you process cameras across different regions or grounds, pass the relevant overrides (region_id, model, species, coordinates) on each call so every image is analysed against the right context.