Batch Detect Urban
1 credit / imagePOST /v1/batch-detect-urbanAnalyze up to 10 urban or human-modified images in one request and receive per-image detection results.
Processing images regularly or at large scale?
Use this synchronous endpoint for first tests, debugging, and small workflows. For steady pipelines, larger files, or bursty camera-fleet uploads, approved customers can use Async Image Processing.
Open Async Image ProcessingExamples
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://api.animaldetect.com/v1/batch-detect-urban', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.ANIMAL_DETECT_API_KEY,
},
body: form,
})
const data = await 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
}
}Parameters
Required
Array of 1-10 images. Combined upload request body limit is 20MB; combined raw image budget is 10MB.
Optional
Optional shared geofencing hint (CCA2/CCA3/full country name).
Confidence threshold between 0.01 and 0.99. Default: 0.2.
Default: `true`. Set to `false` for detector-only `animal`, `human`, or `vehicle` labels.
When `true`, herd animals can use a precise label already found in the same image. Experimental: Denmark only.
Optional shared area hint. Used only when `longitude` and `country` are also present.
Optional shared area hint. Used only when `latitude` and `country` are also present.
Set to `true` to include available image metadata on each batch result item.
Positive integer (1-10). With `classify=true`, returns alternative species candidates on each annotation.
Request Notes
Send multipart/form-data with repeated `images` fields or JSON with a base64 image array. Use `classify=false` for faster coarse labels. Send `latitude` and `longitude` together; they only apply when `country` is also present. Limits: 20MB request body and 10MB combined raw image data. Billing: 1 credit per image.
Status Codes
Notes
- Best for: urban, indoor, roadside, zoo, farm, and other human-modified image batches.
- Use `classify=false` for faster blank filtering. Labels become coarse: `animal`, `human`, or `vehicle`.
- `smooth_herd=true` can replace broad herd labels such as `mammal` with a precise species already present in the image. Experimental: Denmark only.
- `latitude` and `longitude` apply one shared area hint to the full batch and require `country`.
- `metadata=true` includes metadata only for fields found in each image.
- `top_candidate` with `classify=true` can add ranked alternative species to each annotation.