API quickstart

1. Generate an API key

Open the Developer page in your Animal Detect dashboard and create a key under Create new key. Do not expose API keys in frontend code or public repositories.

2. Authenticate requests

Send your key in the Authorization header on every authenticated request:

Also send a User-Agent header that names your application. POST requests without one are refused with 400 USER_AGENT_REQUIRED.

3. Send your first API request

Send one image to /v1/detect and inspect the returned annotations. The response includes detected objects, bounding boxes, labels, and processing details.

curl -X POST "https://api.animaldetect.com/v1/detect" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "User-Agent: MyApp/1.0 (ops@example.com)" \
  -F "image=@/path/to/image.jpg" \
  -F "threshold=0.2" \
  -F "country=USA"

import os
import requests

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": open("/path/to/image.jpg", "rb")},
    data={"threshold": "0.2", "country": "USA"},
)
response.raise_for_status()
result = response.json()

for annotation in result["annotations"]:
    x, y, width, height = annotation["bbox"]  # normalised 0 to 1, top-left origin
    print(annotation["label"], round(annotation["score"], 3), x, y, width, height)

Bounding boxes are [x, y, width, height], normalised to the image size (0 to 1) with the origin at the top-left corner. Multiply by the pixel width and height to draw them.

Every response carries an X-Request-Id header. Include it when writing to support@animaldetect.com and we can look up the exact request. Error bodies are described on the Errors page.

Use the interactive playground to test endpoints before wiring them into your application.