Detect
1 credit / requestPOST /api/v1/detectBest for classical wildlife camera traps. Use this endpoint to analyze one image and get wildlife detections with bounding boxes, labels, and taxonomy details.
Try in PlaygroundRequired Parameters
image(file | base64 string) Image data. Raw image limit is 10MB.
Optional Parameters
country(string) Optional geofencing hint (CCA2/CCA3/full country name).threshold(number) Confidence threshold between 0.01 and 0.99. Default: 0.2.classify(boolean) Optional. Default: `true`. Set to `false` to skip SpeciesNet and return detector-only `animal`, `human`, or `vehicle` labels.smooth_herd(boolean) Optional. When `true`, similar animals in a herd can inherit the more precise label found in the same image.latitude(number) Optional. Used only when `longitude` and `country` are also present. Adds area-level geofencing inside the country.longitude(number) Optional. Used only when `latitude` and `country` are also present. Adds area-level geofencing inside the country.metadata(boolean) Optional. Set to `true` to include available image metadata in the response.
Supports multipart/form-data (recommended for files) and application/json with base64 image. Set `classify=false` for faster detector-only output. Set `smooth_herd=true` to smooth imprecise herd labels to precise labels seen in the same image. `latitude` and `longitude` must be sent together and only have effect when `country` is also present. Set `metadata=true` to request available image metadata. This Vertex-backed route accepts raw images up to 10MB.
Status Codes
200Detection completed.
400Validation error (bad payload/threshold/image).
401Invalid, missing, or revoked API key.
402Credit limit exceeded.
413Payload too large for the Vertex-backed request limit.
429Rate limit exceeded.
500Unexpected internal server error.
503Upstream Vertex service error.
- Best for: classical wildlife camera traps.
- Uses the same camera-trap Vertex SpeciesNet preset as the internal full-detection pipeline.
- Set `classify=false` to run detector-only mode for blank filtering. The response still uses `annotations`, but labels are coarse: `animal`, `human`, or `vehicle`.
- `smooth_herd=true` helps herd images by replacing non-precise labels such as `mammal` with a precise species already present in the same image when the model can do so.
- `latitude` and `longitude` require each other and `country`. Without all three, area-level geofencing has no effect.
- When `metadata=true`, the response includes a `metadata` object only for the fields the source image actually contains.
- Use `/detect-urban` when your imagery is urban, indoor, roadside, zoo, farm, or other human-modified settings.
Node.js / Express
const form = new FormData()
form.append('image', imageFile)
form.append('country', 'USA')
form.append('threshold', '0.2')
form.append('classify', 'true')
form.append('smooth_herd', 'true')
form.append('latitude', '56.834')
form.append('longitude', '9.994')
form.append('metadata', 'true')
const response = await fetch('https://www.animaldetect.com/api/v1/detect', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.ANIMAL_DETECT_API_KEY,
},
body: form,
})
const data = await response.json()Example Response
JSON
{
"id": "5e4e5dbd-2604-46b4-bb87-8f42fd682b08",
"expires_at": "2026-03-12T09:44:20.954Z",
"annotations": [
{
"id": 0,
"bbox": [0.41, 0.82, 0.20, 0.17],
"score": 0.997,
"label": "canine family",
"taxonomy": {
"id": "3184697f-51ad-4608-9a28-9edb5500159c",
"class": "mammalia",
"order": "carnivora",
"family": "canidae",
"genus": "",
"species": ""
}
}
],
"metadata": {
"image_width": 4000,
"image_height": 3000,
"file_size": 2456789
},
"info": {
"processing_time_ms": 919,
"model_version": "mdv1000-speciesnet",
"model_id": "mdv1000-speciesnet",
"country_processed": "USA",
"threshold_applied": 0.2
}
}