API endpoint update

New integrations should use . Existing URLs will keep working for the next few months while teams migrate.

Async image processing

Professional API

Use async jobs when your system processes many images and can wait for results. Create a job, upload the image to the returned URL, submit it, then fetch the result when processing finishes.

Manual onboarding required

Async access is enabled for approved API customers. Billing uses your customer agreement, not self-serve credits.

Pricing indication

Pay as you go

Professional API is priced at $1.75 (€1.50) / 1,000 images processed. Billing is handled manually by invoice.

Use this flow for

Camera fleets that upload continuously or in bursts.
Scheduled imports from storage, partners, or field devices.
Large batches where immediate HTTP responses are not needed.

Endpoint

https://api.animaldetect.com/v1/jobs

Before you start

Store your API key in AD_API_KEY.
Send Authorization: Bearer $AD_API_KEY on every Animal Detect API request.
Do not send image bytes to POST /jobs. Send metadata only.
Keep each async input image within the agreed API file-size limit.

Create a job

Create one job per image. Use operation: "detect" for full detection output. The file name is metadata only.

Create job

export AD_API_KEY="sk_..."
export AD_API_BASE_URL="https://api.animaldetect.com/v1"

CREATE_RESPONSE=$(curl -sS -X POST "$AD_API_BASE_URL/jobs" \
  -H "Authorization: Bearer $AD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: camera-a-2026-06-19-0001" \
  -d '{
    "operation": "detect",
    "filename": "camera-a-0001.jpg",
    "content_type": "image/jpeg",
    "client_reference_id": "camera-a-2026-06-19-0001"
  }')

Upload the image

Upload the image bytes to the signed URL from the create response. This keeps large files out of the API request body.

Upload image

UPLOAD_URL=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.upload.url')

curl -sS -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @camera-a-0001.jpg

Submit the job

Submit the job after the upload succeeds. The job then enters the processing queue.

Submit job

SUBMIT_URL=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.submit_url')

curl -sS -X POST "$SUBMIT_URL" \
  -H "Authorization: Bearer $AD_API_KEY"

Poll status

Poll until status is succeeded or failed. Start with a short interval, then back off for larger queues.

Check status

STATUS_URL=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.status_url')

curl -sS "$STATUS_URL" \
  -H "Authorization: Bearer $AD_API_KEY"

Successful status

{
  "job_id": "5fd3825f-46a3-4892-8600-44a319e2d18f",
  "status": "succeeded",
  "operation": "detect",
  "client_reference_id": "camera-a-2026-06-19-0001",
  "result_url": "https://api.animaldetect.com/v1/jobs/5fd3825f-46a3-4892-8600-44a319e2d18f/result"
}

Fetch the result

Fetch the result JSON after the job succeeds. Store it in your system if you need long-term records.

Fetch result

RESULT_URL=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.result_url')

curl -sS "$RESULT_URL" \
  -H "Authorization: Bearer $AD_API_KEY"

Operational rules

Use one stable Idempotency-Key per image. Reuse it only when retrying the same payload.

Use sync endpoints for onboarding, debugging, and immediate one-image responses.

Results are available only for the API retention window.

Read the full Async Image Processing endpoint contract, or use the API Playground for simple sync tests.