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 [email protected].

API Endpoints

Health Check

get

Returns the overall health status of the application

Authorizations

ApiKeyAuth

x-api-keystringRequired

Responses

200

Healthy

application/json

503

Unhealthy

application/json

get

/health

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())

{
  "status": "healthy"
}

Process an event

post

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

Authorizations

ApiKeyAuth

x-api-keystringRequired

Header parameters

x-api-keystringRequired

Traces API key

Body

multipart/form-data

metadatastring · jsonOptional

JSON string containing event metadata

image_0string · binaryOptional

image_1string · binaryOptional

image_2string · binaryOptional

image_3string · binaryOptional

image_4string · binaryOptional

Responses

200

Successful response

application/json

400

Bad request (invalid input)

500

Internal server error

post

/event/process

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))

{
  "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

get

Retrieve the advanced understanding results for a previously processed event.

Authorizations

ApiKeyAuth

x-api-keystringRequired

Query parameters

task_idstringRequired

The task ID returned from the process event endpoint

Header parameters

x-api-keystringRequired

Traces API key

Responses

200

Successful response

application/json

400

Bad request (invalid input)

404

Task not found

500

Internal server error

get

/event/advanced_understanding

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)

{
  "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.