Prompt Writing Guide – Crawleye Prompt-Based AI Video Analysis

Crawleye’s prompt-based detection lets you move far beyond fixed object detection.
If you can describe it in plain language, our AI can look for it in your video — whether that’s a specific object, a complex action, or a sequence of events.

This guide shows you how to craft powerful prompts that give you exactly the results you want, while keeping your costs and processing time efficient.

1️⃣ Why Prompts Matter

The prompt is your analysis blueprint.
It tells Crawleye’s AI:

What to detect
How to interpret it
When to log it
Any conditions or constraints

A well-crafted prompt can mean the difference between useful, actionable insights and noisy, incomplete results.

2️⃣ Anatomy of a Great Prompt

A strong prompt usually includes:

Element	Why it’s important	Example
Target	The object, person, action, or event you want detected	“Forklifts”, “People without helmets”
Condition	When or where detection should happen	“Only in the loading dock”, “Only if vehicle stops for more than 10 seconds”
Action/Output	What you want done with detections	“Count per 5-minute interval”, “Highlight in annotated video”
Extras	Optional model instructions for OCR, summaries, etc.	“Also extract any visible text on safety signs”

3️⃣ Prompt Examples by Use Case

Security & Compliance

Detect all individuals entering through the side gate after 6 PM.
Flag if any are not wearing safety helmets and record timestamps.

Industrial Operations

Count forklifts entering the loading dock every 5 minutes.
Generate a CSV timeline of counts.

Traffic Monitoring

Track every red truck passing the checkpoint.
Provide total count and annotated preview video.

Research & Science

Identify and count all penguins visible in the clip.
Ignore partial sightings where less than 50% of the penguin is visible.

OCR / Signage

Extract all text from road signs visible in the video.
Include location in frame and timestamp for each sign.

4️⃣ Combining Multiple Goals

Crawleye supports multi-part prompts.
Example:

1. Count the number of forklifts entering the warehouse.
2. Detect any person not wearing a helmet.
3. Provide an LLM summary describing peak activity times.

📌 Tip: Multi-part prompts increase GPU load. For large jobs, break them into separate analyses for speed & cost control.


## 5️⃣ Prompt + Feature Synergy

Your prompt works best when paired with the right features:

| Feature         | When to Use                             | Example Prompt                                        |
|-----------------|----------------------------------------|-------------------------------------------------------|
| `detect_only`   | Basic object/action detection           | “Count red cars in parking lot”                       |
| `ocr`           | Reading text from signs, labels, docs   | “Extract text from all visible signage”               |
| `reid_tracking` | Following specific objects over time    | “Track the same forklift across multiple camera angles” |
| `llm_summary`   | Human-readable report generation        | “Summarize all safety violations in natural language” |

---

## 6️⃣ Writing for Precision

- **Be specific** – “Count red cars” instead of “Count cars”
- **Add conditions** – “Only during daylight hours”
- **Include context** – “In the left half of the frame”
- **Define timeframes** – “Per 10-minute interval”
- **Avoid ambiguity** – Use clear, objective terms

---

## 7️⃣ Testing & Refining Prompts

1. **Test on a short clip** first to confirm accuracy.
2. **Review results** in JSON, CSV, and preview video.
3. **Adjust wording** for better precision.
4. **Iterate** until results match your intended output.
5. Save prompts in your **dashboard** for reuse.

---

## 8️⃣ Prompt Performance Tips

- **Simple beats complex** – Break huge prompts into smaller jobs.
- **Order matters** – List most important detection first.
- **Balance detail vs. speed** – Large models (L_32B) are more accurate but slower & costlier.
- **Use “ignore” instructions** – Helps reduce false positives.

---

## 9️⃣ Prompt API Example

**POST** `/v1/videos/analyze`
```json
{
  "file_id": "abc123",
  "prompt": "Detect people not wearing helmets in the loading dock area after 5 PM.",
  "model_class": "M_13B",
  "features": ["detect_only", "llm_summary"],
  "priority": "standard"
}

## 1️⃣0️⃣ Common Mistakes to Avoid

❌ **Too vague:** “Detect people”
✅ **Better:** “Detect people not wearing safety vests inside construction site”

❌ **Overloaded prompts:** “Detect forklifts, cars, people, and birds while counting signs”
✅ **Better:** Break into 2–3 separate analyses

❌ **No conditions:** Without specifying time, location, or action, AI may return irrelevant results.