Snaps
Snaps let your application reliably send visual data (images, videos, pointclouds) and optional annotations to Luxonis Hub. Once stored as snaps, this data can be browsed, filtered, downloaded, or ingested into HubAI datasets, making them the primary building block for data collection in Luxonis apps. More information about snaps can be found on the Hub's snaps page.Under the hood, snaps are implemented as a special type of event sent via the EventsManager. Sending raw events directly is not supported; as a depthai user, you interact with snaps only.Getting Started
To send snaps from your app, you first create and reuse a single EventsManager instance. In a typical application, you:- Create the
EventsManageronce (for example, next to your pipeline / device setup). - Keep a reference to it in your main application class or context.
- Call
sendSnap()whenever you want to upload visual data to Luxonis Hub.
| Parameter | Description | Example |
|---|---|---|
Name | The primary identifier for a snap | car_detected, gate_open, image |
Files | Attachments uploaded with the snap | ImgFrame, ImgDetections |
Tags (Optional) | Additional filters for grouping and filtering | dataset_collection, Dataset 1, Location 72, Assembly Line 17 |
Extras (Optional) | Additional filters for grouping and filtering | Car brand:volvo, State: open, Location: New York |
Snap Limits
When sending snaps, be aware of the following limits:| Field | Rule |
|---|---|
Name | 1–56 characters (required) |
Files | Max 20 files per snap (Min 1 required) |
Tags | Max 20 tags; each 1–56 characters |
Extras | Max 25 entries; extras.key 1–40 characters; extras.value 0–100 characters |
- Maximum file size
- Remaining storage
- Hourly limits for file uploads (number of files and bandwidth)
- Hourly limits for events and snaps sent
Note: CallingsendSnap()only validates basic parameters and queues the snap for upload. It does not guarantee the snap has been sent to the Hub. A return value oftruemeans the snap has been successfully added to the queue, but it does not confirm successful delivery nor successful file uploads.
Authentication
If you are usingoakctl to run your application, the authentication is handled on your behalf. You do not provide an API key yourself.For oakctl run-script this uses the team you logged into using oakctl hub login. For oakctl app run this uses the team where the device is connected.To send snaps, your team's API Key must be defined. This is typically set using the environment variable DEPTHAI_HUB_API_KEY or inside your application using the EventsManager's setToken() method. When running in standalone mode and adopted to Hub, this environment variable is pre-populated.API Key good practices with practical examples can be found here.Sending Snaps with ImgFrames and ImgDetections
This section demonstrates creating an EventsManager instance and using it to send snaps containing either a single image or an image with detections in a Luxonis DepthAI application.Python
C++
Python
Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Send snap with ImgFrame and ImgDetections
5eventMan.sendSnap(
6 name="snap_name",
7 fileName="file_name",
8 imgFrame=inImgFrame,
9 imgDetections=inImgDetections,
10 tags=["examples", "python"],
11 extras={"confidence": "0.75", "location": "01"},
12 deviceSerialNo="serialNum"
13)Python
C++
Python
Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Send snap with ImgFrame
5eventMan.sendSnap(
6 name="snap_name",
7 fileName=None,
8 imgFrame=inImgFrame,
9 imgDetections=None,
10 tags=[],
11 extras={},
12 deviceSerialNo=""
13)Sending snaps (python)
Sending snaps (C++)
Advanced Use: Sending Snaps using FileGroups
In the examples above, aFileGroup is created automatically from the image (and detections) when using sendSnap(). You can also create a FileGroup explicitly. When sending a FileGroup, all included files are uploaded to the Luxonis Hub together. The group's upload will either fully succeed or fail, depending on your allocated storage capacity - it must be large enough to accommodate all files in the group.The example below demonstrates the same functionality using the FileGroup object explicitly. This approach involves creating a FileGroup instance and adding files to it. Common file pairs, such as ImgFrame and ImgDetections, can be added simultaneously, or separately as individual files. More information can be found in the FileGroup class documentation.Python
C++
Python
Python
1# Create the EventsManager instance
2eventMan = dai.EventsManager()
3
4# Create the FileGroup instance
5fileGroup = dai.FileGroup()
6
7# Add files to fileGroup
8fileGroup.addImageDetectionsPair("file_name", inImgFrame, inImgDetections)
9
10# Send snap with the fileGroup
11eventMan.sendSnap(
12 name="snap_name",
13 fileGroup=fileGroup,
14 tags=["examples", "python"],
15 extras={"confidence": "0.75", "location": "01"},
16 deviceSerialNo="serialNum"
17)Sending snaps using a FileGroup (python)
Sending snaps using a FileGroup (C++)
How and when are snaps uploaded to the Hub?
DepthAI uploads and sends events in batches, which means multipleFileGroup instances or snaps are grouped together in a single request. Batches are sent at regular intervals (by default every 30 seconds), which may cause a brief delay before snaps appear in the Hub. For increased batch frequency, please contact support.