Crawleye API Reference – Prompt-Based AI Video Analysis

Crawleye’s API lets you connect any video source—uploaded clips or live RTSP feeds—and run prompt-driven AI analysis to detect, track, and summarize exactly what you describe.

1️⃣ Authentication

API Keys

Get your API key from the Dashboard → API Keys
Send in the X-API-Key header for every request
Keys are scoped per project; regenerate if compromised

Example:

curl -X GET "https://api.crawleye.com/v1/usage" \
  -H "X-API-Key: YOUR_API_KEY"

  2️⃣ Video Upload Workflow

Crawleye uses a two-step upload process with presigned URLs for speed and security.

Create an Upload URL

POST /v1/videos/upload

Response:

{
  "upload_url": "https://storage.crawleye.com/uploads/xyz123?signature=...",
  "file_id": "xyz123",
  "expires_at": "2025-08-10T12:00:00Z"
}

Upload Your Video

Use PUT or multipart upload to the upload_url.
Supported formats: .mp4, .avi, .mov, .mkv

⸻

3️⃣ Start an Analysis

POST /v1/videos/analyze

Request Body:

{
  "file_id": "xyz123",
  "prompt": "Count forklifts entering loading dock every 5 minutes",
  "model_class": "M_13B",
  "features": ["detect_only", "ocr"],
  "priority": "standard",
  "webhook_url": "https://example.com/webhook"
}

Parameters:
  •  prompt (string) – Your natural language instruction (can be anything you want detected/analyzed)
  •  model_class (string) – S_7B, M_13B, L_32B
  •  features (array) – Any combination:
  •  detect_only
  •  ocr
  •  reid_tracking
  •  llm_summary
  •  priority (string) – standard or priority (faster processing, higher cost)
  •  webhook_url (string) – Optional, for automatic results delivery

Response:

{
  "job_id": "job_abc123",
  "status": "queued",
  "cost_estimate_usd": 0.85
}

4️⃣ Check Job Status

GET /v1/jobs/{job_id}

Response:

{
  "id": "job_abc123",
  "status": "processing",
  "progress": 45,
  "cost_estimate_usd": 0.85,
  "final_charge_usd": null
}

5️⃣ Retrieve Results

GET /v1/videos/{video_id}/results

Response:

{
  "id": "video_abc123",
  "summary_text": "3 forklifts entered loading dock in total.",
  "detections_url": "https://storage.crawleye.com/results/video_abc123/detections.json",
  "timeline_csv_url": "https://storage.crawleye.com/results/video_abc123/timeline.csv",
  "preview_mp4_url": "https://storage.crawleye.com/results/video_abc123/annotated.mp4",
  "meta": {
    "prompt": "Count forklifts entering loading dock every 5 minutes",
    "model_class": "M_13B",
    "features": ["detect_only", "ocr"]
  }
}

6️⃣ Live RTSP Camera Analysis

POST /v1/cameras – Add a new camera
POST /v1/cameras/{camera_id}/analyze – Run prompt-based analysis on live feed

Example:

{
  "camera_id": "cam_456",
  "prompt": "Detect all vehicles stopping in front gate area for more than 10 seconds",
  "model_class": "S_7B",
  "features": ["detect_only"],
  "priority": "priority"
}

7️⃣ Usage & Billing

Get Usage

GET /v1/usage

{
  "media_minutes_processed": 143,
  "storage_gb_month": 2.5,
  "charges_usd": 24.65,
  "credits_remaining_minutes": 57
}

Get Pricing

GET /v1/pricing

[
  {
    "model_class": "S_7B",
    "feature_set": ["detect_only"],
    "price_per_min_usd": 0.09
  }
]


8️⃣ Webhooks

When webhook_url is set, Crawleye sends:

{
  "event": "job.completed",
  "job_id": "job_abc123",
  "video_id": "video_abc123",
  "status": "completed",
  "results_url": "https://api.crawleye.com/v1/videos/video_abc123/results"
}


9️⃣ Rate Limits
  •  Standard: 120 requests/min/project
  •  Burst: 300 requests/min/project
  •  Contact support for enterprise increases

⸻

1️⃣0️⃣ Error Codes


Code
Meaning
400
Invalid request parameters
401
Missing/invalid API key
403
Access denied
404
Resource not found
429
Too many requests
500
Server error


1️⃣1️⃣ Best Practices for Prompt-Based Analysis
  •  Be explicit in prompts (“count red cars” vs. “detect cars”)
  •  Break complex tasks into multiple analyses
  •  Use priority only when needed (higher GPU cost)
  •  Store results externally for long-term archives