Detect URL
1 credit / requestPOST /v1/detect-urlUse this endpoint to analyze a public image URL and get the same camera-trap detection output as `/detect` without uploading a file.
Try in PlaygroundRequired Parameters
url(string) Public image URL.
Optional Parameters
country(string) Optional geofencing hint (CCA2/CCA3/full country name).threshold(number) Confidence threshold between 0.01 and 0.99. Default: 0.2.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. Experimental: currently supported only in Denmark.latitude(number) Optional. Used only when `longitude` and `country` are also present. Adds area-level geofencing inside the country.longitude(number) Optional. Used only when `latitude` and `country` are also present. Adds area-level geofencing inside the country.metadata(boolean) Optional. Set to `true` to include available image metadata in the response.top_candidate(integer) Optional. Positive integer (1-10). Only used when `classify` is `true`. Returns alternative species candidates on each annotation.
Request body is JSON only. 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. Experimental: currently supported only in Denmark. `latitude` and `longitude` must be sent together and only have effect when `country` is also present. Set `metadata=true` to request available image metadata. Set `top_candidate` to include ranked alternative species on each annotation in classify mode. Private IPs and internal targets are blocked by URL security checks. Keep fetched images up to 10MB raw.
Status Codes
200Detection completed.
400Validation error or blocked URL target.
401Invalid, missing, or revoked API key.
402Credit limit exceeded.
413Fetched image is too large for the endpoint limit.
429Rate limit exceeded.
500Unexpected internal server error.
503AI processing service temporarily unavailable.
- Set `classify=false` to run detector-only mode for blank filtering. The response still uses `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. Experimental: currently supported only in Denmark.
- `latitude` and `longitude` require each other and `country`. Without all three, area-level geofencing has no effect.
- When `metadata=true`, the response includes a `metadata` object only for the fields the fetched image actually contains.
- When `top_candidate` is set with `classify=true`, each annotation may include `top_candidates` with ranked alternative species.
Node.js / Express
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()Example 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"
}
}