Detect URL
Metered / request/v1/detect-urlAnalyse a public image URL and return the same detection output as /detect, without uploading a file.
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
Public image URL.
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 JSON only. Use classify=false for faster coarse labels. Send latitude and longitude together; they only apply when country is also present. Private IPs and internal targets are blocked. Fetched images must be 10 MB or smaller.
Status codes
Notes
- 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 fetched image.top_candidatewithclassify=truecan add ranked alternative species to each annotation.
Examples
const response = await fetch('https://api.animaldetect.com/v1/detect-url', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.ANIMAL_DETECT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: 'https://example.com/camera-trap.jpg',
country: 'USA',
threshold: 0.2,
classify: true,
smooth_herd: true,
latitude: 56.834,
longitude: 9.994,
metadata: true,
top_candidate: 2,
}),
})
const data = await response.json(){
"id": "70dc39be-e013-4ea5-bbc5-a3832f7fc310",
"expires_at": "2026-03-12T09:44:20.954Z",
"annotations": [],
"metadata": {
"image_width": 4000,
"image_height": 3000,
"file_size": 2456789
},
"info": {
"processing_time_ms": 884,
"model_version": "mdv1000-speciesnet",
"model_id": "mdv1000-speciesnet",
"country_processed": "USA",
"threshold_applied": 0.2,
"source_url": "https://example.com/camera-trap.jpg"
}
}