Batch Detect Urban
1 credit / imagePOST /api/v1/batch-detect-urbanBest for urban, indoor, roadside, zoo, farm, and other human-modified settings when you need bounding boxes plus taxonomy-rich labels across many files.
Try in PlaygroundRequired Parameters
images(file[] | base64[]) Array of 1-10 images. Combined raw image limit is 10MB.
Optional Parameters
country(string) Optional shared 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 shared area hint. Used only when `longitude` and `country` are also present.longitude(number) Optional shared area hint. Used only when `latitude` and `country` are also present.metadata(boolean) Optional. Set to `true` to include available image metadata on each batch result item.
Supports multipart/form-data (`images` repeated) and application/json with base64 string array. 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 combined raw image payloads up to 10MB.
Status Codes
200Batch detection completed.
400Validation error (empty list, too many images, invalid threshold).
413Batch payload too large for the Vertex-backed request limit.
401Invalid, missing, or revoked API key.
402Credit limit exceeded.
429Rate limit exceeded.
503Upstream Vertex service error.
- Best for: bulk urban-focused detection with taxonomy-rich output.
- Set `classify=false` to run detector-only mode. Result items still use `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` apply one shared area hint to the full batch and require `country`.
- When `metadata=true`, each batch result item includes a `metadata` object only for the fields that image actually contains.
Node.js / Express
const form = new FormData()
form.append('images', firstFile)
form.append('images', secondFile)
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/batch-detect-urban', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.ANIMAL_DETECT_API_KEY,
},
body: form,
})
const data = await response.json()Example Response
JSON
{
"id": "f7956216-c346-4fbf-a693-3eefc0148125",
"expires_at": "2026-03-12T09:44:20.954Z",
"results": [
{
"index": 0,
"filename": "street-fox.jpg",
"annotations": [],
"metadata": {
"image_width": 4000,
"image_height": 3000,
"file_size": 2456789
},
"info": {
"processing_time_ms": 410,
"model_version": "mdv5-speciesnet",
"model_id": "mdv5-speciesnet",
"country_processed": "USA",
"threshold_applied": 0.2
}
}
],
"info": {
"total_processed": 1,
"total_time_ms": 410,
"model_version": "mdv5-speciesnet",
"model_id": "mdv5-speciesnet",
"country_processed": "USA",
"threshold_applied": 0.2
}
}