Batch Detect
1 credit / imagePOST /api/v1/batch-detectBest for classical wildlife camera traps. Use this endpoint to analyze up to 10 images in one request and receive per-image detection results in a single response.
Try in PlaygroundRequired Parameters
images(file[] | base64[]) Array of 1-10 images. Combined raw image limit is 10MB.
Optional Parameters
threshold(number) Confidence threshold between 0.01 and 0.99. Default: 0.2.country(string) Optional shared geofencing hint (CCA2/CCA3/full country name) applied to every image in the batch.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. Billing is 1 credit per image in the batch.
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.
500Unexpected internal server error.
503Upstream Vertex service error.
- Best for: classical wildlife camera-trap image batches.
- Batch items are sent to Vertex together in one request instead of being looped sequentially through the legacy proxy.
- When `metadata=true`, each batch result item includes a `metadata` object only for the fields that image actually contains.
- Optional `country` applies one shared geofencing hint to the full batch.
- 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`.
- Use `/batch-detect-urban` when your batch is urban, indoor, roadside, zoo, farm, or other human-modified settings.
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', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.ANIMAL_DETECT_API_KEY,
},
body: form,
})
const data = await response.json()Example Response
JSON
{
"id": "aa367f74-fd47-4ce3-97d6-12f48f3e6d03",
"expires_at": "2026-03-12T09:44:20.954Z",
"results": [
{
"index": 0,
"filename": "cam-1.jpg",
"annotations": [],
"metadata": {
"image_width": 4000,
"image_height": 3000,
"file_size": 2456789
},
"info": {
"processing_time_ms": 643,
"model_version": "mdv1000-speciesnet",
"model_id": "mdv1000-speciesnet",
"threshold_applied": 0.2
}
}
],
"info": {
"total_processed": 1,
"total_time_ms": 643,
"model_version": "mdv1000-speciesnet",
"model_id": "mdv1000-speciesnet",
"country_processed": "USA",
"threshold_applied": 0.2
}
}