💻
API
  • Introduction
  • Development Quickstart
  • Сluster URL structure
  • API Reference
  • False Alarm Filtering (FAF)
    • FAF API
    • Best Practices
    • How to Connect
  • Advanced Event Understanding
  • Counting
    • Counting API
    • Best Practises
  • People Search
  • Solutions
Powered by GitBook
On this page

Was this helpful?

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 support@traces.ai.

API Endpoints

Examples

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

PreviousHow to ConnectNextCounting

Last updated 7 months ago

Was this helpful?

Input data

Health Check

get

Returns the overall health status of the application

Authorizations
Responses
200
Healthy
application/json
503
Unhealthy
application/json
get
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
Header parameters
x-api-keystringRequired

Traces API key

Body
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
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
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
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"
    }
  }
}
  • Introduction
  • Key Features
  • Authentication
  • API Endpoints
  • GETHealth Check
  • POSTProcess an event
  • GETGet advanced understanding of an event
  • Examples
  • Advanced Features