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.metadata(boolean) Optional. Set to `true` to include available image metadata in the response.
Request body is JSON only. Set `metadata=true` to request available image metadata in the response. Private IPs and internal targets are blocked by URL security checks. Keep fetched images around 1.1MB raw or less so the upstream Vertex request stays below its current 1.5MB limit.
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 current Vertex-backed payload limit.
429Rate limit exceeded.
500Unexpected internal server error.
503Vertex inference service temporarily unavailable.
- 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,
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"
}
}