Detect URL
1 credit / requestPOST /api/v1/detect-urlUse this endpoint to analyze a public image URL and get the same Vertex-backed 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.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.
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. `latitude` and `longitude` must be sent together and only have effect when `country` is also present. Set `metadata=true` to request available image metadata. 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 Vertex-backed payload limit.
429Rate limit exceeded.
500Unexpected internal server error.
503Vertex inference 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.
- `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.
Node.js / Express
const response = await fetch('https://www.animaldetect.com/api/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,
}),
})
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"
}
}