Advanced Event Understanding

Introduction

Welcome to the Advanced Event Understanding API, a cutting-edge solution for sophisticated event analysis and interpretation. Our API harnesses the power of advanced AI technology to provide deep, real-time insights for your security and surveillance applications. By processing multiple images and associated metadata, our system offers unparalleled event comprehension, enabling you to make informed decisions quickly and efficiently.

Key Features

• Efficient Multi-Image Processing: Analyze 5 or more strategic images per event, providing comprehensive understanding without the need for extensive data transfer.

• Advanced AI Interpretation: Extract deep insights from limited visual data, offering sophisticated event analysis that rivals full video processing.

• Real-time Analysis: Receive instant results for time-critical decision-making.

• Flexible Integration: Seamlessly incorporate our RESTful API into your existing systems.

• Secure Communication: Protect your data with robust API key authentication.

Authentication

All API requests require authentication using an API key. Include your API key in the x-api-key header for all requests. If you don't have an API key, you can obtain one by contacting our support team at [e-mail].

API Endpoints

Health Check

Returns the overall health status of the application

GET/health

Authorization

ApiKeyAuth

Response

200503

Healthy

Body

application/json

statusenum

Example: "healthy"

healthyunhealthy

Request

PythonCurl

import requests

url = "https://k0.traces.cloud/health"
headers = {"x-api-key": "TRACES_API_KEY"}
response = requests.get(url, headers=headers)
print(response.json())

Response

200503

{
  "status": "healthy"
}

Process an event

Handle multipart form data containing metadata and images, process them, and return a response with filtering report and task ID for advanced understanding.

POST/event/process

Authorization

ApiKeyAuth

Header parameters

Body

multipart/form-data

metadatastring (json)

JSON string containing event metadata

image_0string (binary)

image_1string (binary)

image_2string (binary)

image_3string (binary)

image_4string (binary)

Response

200400500

Successful response

Body

application/json

advanced_understanding_task_idstring

filtering_reportAlarmReport (object)

Request

PythonCurl

import requests
import json
import os

def process_event(image_paths, metadata):
  url = 'https://k0.traces.cloud/api/v1/event/process'
  headers = {'x-api-key': 'TRACES_API_KEY'}

  files = {}
  for i, path in enumerate(image_paths):
    with open(path, 'rb') as img_file:
      files[f'image_{i}'] = (f'image_{i}.png', img_file.read())

  data = {'metadata': json.dumps(metadata)}
  response = requests.post(url, headers=headers, data=data, files=files)
  
  return response.json()

# Example usage
image_paths = [
  'path/to/image1.png',
  'path/to/image2.png',
  'path/to/image3.png',
  'path/to/image4.png',
  'path/to/image5.png'
]

metadata = {
  'camera_id': 'b5271b30-aecd-4897-bc95-ff25c8466b9t',
  'event_id': 'ddf27b34-d3b5-41a5-b2a6-3873a589ec09',
  'timestamp': 1585840725
}

result = process_event(image_paths, metadata)
print(json.dumps(result, indent=2))

Response

200

{
  "advanced_understanding_task_id": "123e4567-e89b-12d3-a456-426614174000",
  "filtering_report": {
    "alarm_confirmed": true,
    "alarm_confidence": 0.95,
    "triggered_by": [
      {
        "object_type": "vehicle",
        "object_class": "truck",
        "action": "moving",
        "bbox": [
          10,
          20,
          100,
          200
        ],
        "frame_id": 0,
        "direction": "None",
        "object_color": "red"
      }
    ]
  }
}

Get advanced understanding of an event

Retrieve the advanced understanding results for a previously processed event.

GET/event/advanced_understanding

Authorization

ApiKeyAuth

Query parameters

Header parameters

Response

200400404500

Successful response

Body

application/json

statusenum

processingcompletedfailed

resultEventUnderstandingOutput (object)

Request

PythonCurl

import requests

url = "https://k0.traces.cloud/api/v1/event/advanced_understanding"
params = {"task_id": "123e4567-e89b-12d3-a456-426614174000"}
headers = {"x-api-key": "TRACES_API_KEY"}

response = requests.get(url, params=params, headers=headers)

Response

200

{
  "status": "completed",
  "result": {
    "event_summary": "A person wearing a light-colored hoodie approaches a black car parked on the side of a street. The person appears to attempt to open the side door, but the car is locked. The person gains entry to the car.",
    "predicted_attributes": {
      "people_descriptions": [
        "light-colored hoodie",
        "dark jeans"
      ],
      "people_actions": [
        "trying to break in"
      ],
      "logos": [
        "None"
      ],
      "vehicle_descriptions": [
        "a black car"
      ],
      "vehicle_actions": [
        "parked"
      ],
      "suspicion_status": "highly suspicious"
    }
  }
}

Examples

Input data

{
  "status": "completed",
  "result": {
    "event_summary": "A person wearing a light-colored hoodie approaches a black car parked on the side of a street. The person appears to attempt to open the side door, but the car is locked. The person gains entry to the car.",
    "predicted_attributes": {
      "people_descriptions": [
        "light-colored hoodie",
        "dark jeans"
      ],
      "people_actions": [
        "trying to break in"
      ],
      "logos": [
        "None"
      ],
      "vehicle_descriptions": [
        "a black car"
      ],
      "vehicle_actions": [
        "parked"
      ],
      "suspicion_status": "highly suspicious"
    }
  }
}

Advanced Features

Our Advanced Event Understanding API offers a range of sophisticated capabilities:

1. Multi-image Analysis: Process 5 or more images per event for comprehensive understanding.

2. Object Detection and Classification: Identify and categorize objects, people, and vehicles in the scene.

3. Action Recognition: Understand and interpret the actions and behaviors of detected entities.

4. Contextual Analysis: Evaluate the overall situation and relationships between objects and actions.

5. Natural Language Summaries: Generate human-readable descriptions of events for quick comprehension.

6. Suspicion Assessment: Automatically evaluate the potential threat level of events.