Detect
Metered / request/v1/detectAnalyse one camera trap image and return detected animals with bounding boxes, labels, and taxonomy details.
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
Image data. Upload request body limit is 20 MB; raw image budget is 10 MB.
Optional
Optional 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. Used only when longitude and country are also present. Adds area-level geofencing inside the country.
Optional. Used only when latitude and country are also present. Adds area-level geofencing inside the country.
Set to true to include available image metadata in the response.
Positive integer (1-10). With classify=true, returns alternative species candidates on each annotation.
Request notes
Send multipart/form-data for files or JSON with a base64 image. Use classify=false for faster coarse labels. Send latitude and longitude together; they only apply when country is also present. Limits: 20 MB request body and 10 MB raw image.
Response fields
Required. Request id. Also sent as the X-Request-Id header; use it with GET /detect/{id} and when writing to support.
Required. When GET /detect/{id} stops returning this result.
Required. One entry per detected object. Empty when nothing scored above threshold.
Required. Position of the detection in this response, starting at 0.
Required. Bounding box as [x, y, width, height], normalised to the image size (0 to 1), origin at the top-left corner. Multiply by the pixel width and height to draw it.
Required. Confidence of the label.
Required. Most specific label the model committed to (species, family, or animal, human, vehicle with classify=false).
Required. id, class, order, family, genus, species. Levels the model did not resolve are empty strings.
Optional. Ranked alternative labels with label, score, taxonomy. Present only when top_candidate was sent with classify=true.
Optional. Image metadata found in the file (image_width, image_height, file_size, EXIF fields when present). Only with metadata=true.
Required. processing_time_ms, model_id, model_version, threshold_applied, and country_processed when a country was recognised.
Optional. Present when the country value was not recognised and the request ran without geofencing.
Status codes
Notes
- POST requests must send a
User-Agentheader that names your application; without one the API answers 400USER_AGENT_REQUIRED. - Best for: classical wildlife camera traps.
- Use
classify=falsefor faster blank filtering. Labels become coarse:animal,human, orvehicle. smooth_herd=truecan replace broad herd labels such asmammalwith a precise species already present in the image. Experimental: Denmark only.latitudeandlongituderequire each other andcountry. Without all three, area-level geofencing has no effect.metadata=trueincludes metadata only for fields found in the source image.top_candidatewithclassify=truecan add ranked alternative species to each annotation.- Use
/detect-urbanfor urban, indoor, roadside, zoo, farm, or other human-modified scenes.
Examples
curl -X POST "https://api.animaldetect.com/v1/detect" -H "Authorization: Bearer $ANIMAL_DETECT_API_KEY" -H "User-Agent: MyApp/1.0 (ops@example.com)" -F "image=@/path/to/camera-trap.jpg" -F "country=USA" -F "threshold=0.2" -F "classify=true" -F "smooth_herd=true" -F "latitude=56.834" -F "longitude=9.994" -F "metadata=true" -F "top_candidate=2"import os
import requests
with open("/path/to/camera-trap.jpg", "rb") as image:
response = requests.post(
"https://api.animaldetect.com/v1/detect",
headers={
"Authorization": "Bearer " + os.environ["ANIMAL_DETECT_API_KEY"],
"User-Agent": "MyApp/1.0 (ops@example.com)",
},
files={"image": image},
data={
"country": "USA",
"threshold": "0.2",
"classify": "true",
"smooth_herd": "true",
"latitude": "56.834",
"longitude": "9.994",
"metadata": "true",
"top_candidate": "2"
},
)
response.raise_for_status()
data = response.json()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')
form.append('top_candidate', '2')
const response = await fetch('https://api.animaldetect.com/v1/detect', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.ANIMAL_DETECT_API_KEY,
},
body: form,
})
const data = await 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": ""
},
"top_candidates": [
{
"label": "red fox",
"score": 0.18,
"taxonomy": {
"id": "11111111-1111-4111-8111-111111111111",
"class": "mammalia",
"order": "carnivora",
"family": "canidae",
"genus": "vulpes",
"species": "vulpes"
}
}
]
}
],
"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
}
}