Filter Urban
Metered / requestPOST
/v1/filter-urbanQuickly separate empty urban or human-modified images from images with an animal, human, or vehicle. Returns bounding boxes and coarse labels only.
Processing images regularly or at large scale?
Use this Instant detection endpoint for first tests, debugging, and small workflows. For steady pipelines, larger files, or bursty camera-fleet uploads, approved customers can use Detection jobs.
Open Detection jobsParameters
Required
file | base64 string
Image data. Upload request body limit is 20 MB; raw image budget is 10 MB.
Optional
string
Optional geofencing hint (CCA2/CCA3/full country name).
number
Confidence threshold between 0.01 and 0.99. Default: 0.2.
boolean
Set to true to include available image metadata in the response.
Request notes
Send multipart/form-data for files or JSON with a base64 image. Limits: 20 MB request body and 10 MB raw image.
Status codes
200Filtering completed.
400Validation error (bad payload, threshold, or image).
401Invalid, missing, or revoked API key.
402Free monthly quota used up and no active API billing, or API keys paused.
413Payload too large for the Instant detection upload limit.
429Rate limit exceeded.
503AI processing service temporarily unavailable.
Notes
- Best for: urban, indoor, roadside, zoo, farm, and other human-modified empty-vs-object screening.
metadata=trueincludes metadata only for fields found in the source image.- Returns only coarse categories:
animal,human,vehicle.
Examples
Node.js / Express
const form = new FormData()
form.append('image', imageFile)
form.append('threshold', '0.2')
form.append('metadata', 'true')
const response = await fetch('https://api.animaldetect.com/v1/filter-urban', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.ANIMAL_DETECT_API_KEY,
},
body: form,
})
const data = await response.json()Example response
{
"id": "753c34fb-9202-4da2-b1d5-3f0c020db674",
"expires_at": "2026-03-12T09:44:20.954Z",
"detections": [
{
"id": 0,
"bbox": [0.22, 0.18, 0.41, 0.53],
"score": 0.96,
"label": "human",
"category": "human"
}
],
"metadata": {
"image_width": 4000,
"image_height": 3000,
"file_size": 2456789
},
"info": {
"processing_time_ms": 388,
"model_version": "mdv5",
"model_id": "mdv5",
"threshold_applied": 0.2
}
}