This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/vision/*.
Vision AI API
Computer vision services for camera management, food recognition, drive-thru analysis, product identification, surveillance events, and ghost inventory detection.
Overview
| Attribute | Value |
|---|---|
| Base Path | /api/v1/vision |
| Authentication | Bearer Token |
| Required Roles | inventory_manager, kitchen, manager, restaurant_manager, tenant_admin, platform_admin, system_admin, super_admin |
| Proxy | Go gateway forwards all /v1/vision/* requests to Python Analytics service at /api/vision/* |
Camera Management
Register Camera
Add a camera to the vision system by providing its RTSP stream URL.
POST /api/v1/vision/cameras
Request Body
{
"camera_id": "cam_001",
"rtsp_url": "rtsp://192.168.1.100:554/stream",
"name": "Kitchen Expo Cam"
}
| Field | Type | Required | Description |
|---|---|---|---|
camera_id | string | Yes | Unique camera identifier |
rtsp_url | string | Yes | RTSP stream URL |
name | string | Yes | Human-readable camera name |
Response
{
"status": "success",
"message": "Camera cam_001 added"
}
List Cameras
Retrieve all configured cameras and their stream URLs.
GET /api/v1/vision/cameras
Response
[
{
"camera_id": "cam_001",
"rtsp_url": "rtsp://192.168.1.100:554/stream"
},
{
"camera_id": "cam_002",
"rtsp_url": "rtsp://192.168.1.101:554/stream"
}
]
Get Camera Analytics
Get queue length and wait time analytics for a specific camera.
GET /api/v1/vision/cameras/{camera_id}/analytics
Path Parameters
| Parameter | Type | Description |
|---|---|---|
camera_id | string | Camera identifier |
Response
{
"camera_id": "cam_001",
"queue_length": 5,
"wait_time": 120.5
}
| Field | Type | Description |
|---|---|---|
camera_id | string | Camera identifier |
queue_length | integer | Detected queue length |
wait_time | float | Estimated wait time in seconds |
Surveillance Events
Get Surveillance Events
Retrieve recent surveillance events (safety, security, compliance) for a tenant.
GET /api/v1/vision/surveillance/events
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
tenant_id | string | Yes | Tenant identifier |
limit | integer | No | Maximum events to return, 1-100 (default: 50) |
Response
Returns an array of surveillance event objects from the VisionEventRepository.
Food Recognition
Recognize Food Items
Recognize food items in an uploaded image and upload the image for verification. Uses edge inference for item detection.
POST /api/v1/vision/food/recognize
Request: multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | Image file (JPEG, PNG) |
tenant_id | query | Yes | Tenant ID for storage isolation |
Response
{
"verified": true,
"items": [
{
"name": "Ribeye Steak",
"confidence": 0.92,
"bounding_box": {"x": 150, "y": 100, "width": 200, "height": 150}
},
{
"name": "French Fries",
"confidence": 0.95,
"bounding_box": {"x": 350, "y": 120, "width": 100, "height": 80}
}
],
"total_count": 2,
"image_url": "https://storage.example.com/drive_thru/verification/abc123.jpg"
}
| Field | Type | Description |
|---|---|---|
verified | boolean | Whether the items match expectations |
items | array | Detected food items with confidence and positions |
total_count | integer | Number of items detected |
image_url | string | URL of the uploaded verification image (may be null) |
Drive-Thru Analysis
Analyze Drive-Thru Image
Analyze a drive-thru lane image for vehicles and license plates.
POST /api/v1/vision/drive-thru/analyze
Request: multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | Drive-thru lane image file |
Response
{
"vehicle_detected": true,
"license_plate": "ABC-1234",
"vehicle_type": "sedan",
"color": "blue",
"confidence": 0.95
}
| Field | Type | Description |
|---|---|---|
vehicle_detected | boolean | Whether a vehicle was detected |
license_plate | string | Detected license plate text |
vehicle_type | string | Vehicle classification (sedan, suv, truck, etc.) |
color | string | Detected vehicle color |
confidence | float | Detection confidence (0.0 to 1.0) |
Product Identification
Identify Product
Identify a product from an image using Vision AI (Instant Catalog). Routes through the AI Gateway for cost-optimized inference.
POST /api/v1/vision/products/identify
Request: multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | Product image file |
tenant_id | query | Yes | Tenant ID for billing |
Response
Returns product identification results from the ProductRecognitionService. The exact response shape depends on the AI model used.
Ghost Inventory Detection
Detect Inventory Discrepancies
Detect inventory discrepancies using Vision AI. Compares visual counts from stock room images with system on-hand values to identify "ghost inventory" (items recorded in the system but not physically present).
POST /api/v1/vision/inventory/detect-discrepancies
Request: multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | Stock room image file |
tenant_id | query | Yes | Tenant identifier |
location_id | query | Yes | Location identifier |
target_items | query | Yes | List of item names to count (repeated query param) |
Response
Returns discrepancy detection results from the GhostInventoryDetector, comparing visual counts against system inventory.
Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid image format or missing tenant_id |
| 500 | Internal Error | Vision service, inference, or storage failure |
Related Documentation
- Vision AI Guide - Setup guide
- Vision AI Compliance - Privacy & compliance
- Drive-Thru - Drive-thru operations