Video Operations

This page describes all SDK methods for video operations. For in-depth code walkthroughs, see SDK Usage Examples.

upload()

Upload one or many local files or URLs.

# Single file
result = client.upload("video.mp4")

# Multiple files
batch = client.upload(["a.mp4", "b.mp4"])

# With folder organization
result = client.upload("video.mp4", folder="my_folder")

Required Parameters:

Parameter	Type	Description
`videos`	`str \| Path \| Sequence[str \| Path]`	Single file/URL or list of files/URLs

Optional Parameters:

Parameter	Type	Default	Description
`folder`	`str`	`None`	Folder name for organizing uploads
`upload_timeout`	`int`	`1200`	Timeout in seconds for upload completion
`wait_for_uploaded`	`bool`	`True`	Wait until upload is complete

Returns: Dict (single) or List[Dict] (multiple) with video_id and status

analyze()

Run analysis on one or more uploaded videos with different analysis types.


# We offer 3 analsis types

# Rapid Review: Custom event detection
client.analyze("abc123", 
    analysis_type=AnalysisType.RAPID_REVIEW,
    custom_event="green crosswalk",
    custom_category=CustomCategory.DRIVING
)

# With thumbnail generation (creates annotated bounding box thumbnails)
client.analyze("abc123", 
    analysis_type=AnalysisType.RAPID_REVIEW,
    custom_event="yellow taxi",
    custom_category=CustomCategory.DRIVING,
    is_thumbnail=True
)

# Edge case detection
client.analyze("abc123",
    analysis_type=AnalysisType.EDGE_CASE,
    edge_case_category="infrastructure-monitoring"
)

# Long Video Semantic search
client.analyze("abc123",
    analysis_type=AnalysisType.SEARCH,
    search_query="Find parked cars"
)

RAPID_REVIEW Analysis

Detect custom events in videos using natural language descriptions. Perfect for finding specific scenarios like “green crosswalk” or “yellow taxi”. Good for videos under 45 mins, and getting results in seconds. Required Parameters:

Parameter	Type	Description
`id(s)` or `folder`	`str \| Sequence[str]`	Video ID(s) or folder name (use one, not both)
`analysis_type`	`AnalysisType`	Must be `AnalysisType.RAPID_REVIEW`
`custom_event`	`str`	Event description to detect (e.g., “green crosswalk”)
`custom_category`	`CustomCategory \| str`	Category context (e.g., `CustomCategory.DRIVING`)

nomadicml.video.CustomCategory

CustomCategory.DRIVING
CustomCategory.ROBOTICS
CustomCategory.AERIAL
CustomCategory.SECURITY
CustomCategory.ENVIRONMENT

Optional Parameters:

Parameter	Type	Default	Description
`model_id`	`str`	`"Nomadic-VL-XLarge"`	AI model to use
`timeout`	`int`	`2400`	Analysis timeout in seconds
`wait_for_completion`	`bool`	`True`	Wait for analysis to complete
`is_thumbnail`	`bool`	`False`	Generate annotated bounding box thumbnails
`return_subset`	`bool`	`False`	Return subset of results

Returns: Dict with video_id, analysis_id, mode, status, summary, and events. If is_thumbnail=True, each event includes an annotated_thumbnail_url.

EDGE_CASE Analysis

Specialized detection for edge cases in specific domains like infrastructure monitoring. You must first define detailed ege case categories in out web platfrom. Good for high quality, in depth analyses. Required Parameters:

Parameter	Type	Description
`ids` or `folder`	`str \| Sequence[str]`	Video ID(s) or folder name (use one, not both)
`analysis_type`	`AnalysisType`	Must be `AnalysisType.EDGE_CASE`
`edge_case_category`	`str`	Edge case category (e.g., “infrastructure-monitoring”)

Optional Parameters:

Parameter	Type	Default	Description
`model_id`	`str`	`"Nomadic-VL-XLarge"`	AI model to use
`timeout`	`int`	`2400`	Analysis timeout in seconds
`wait_for_completion`	`bool`	`True`	Wait for analysis to complete
`concept_ids`	`List[str]`	`None`	Concept IDs for specialized detection
`mode`	`str`	`"assistant"`	Analysis mode: “assistant” or “agent”
`return_subset`	`bool`	`False`	Return subset of results

Returns: Dict with video_id, analysis_id, mode, status, and events.

SEARCH Analysis

Semantic search within long videos to find specific moments matching natural language queries. Use it for videos >45 minutes. Required Parameters:

Parameter	Type	Description
`ids` or `folder`	`str \| Sequence[str]`	Video ID(s) or folder name (use one, not both)
`analysis_type`	`AnalysisType`	Must be `AnalysisType.SEARCH`
`search_query`	`str`	Natural language search query (e.g., “Find parked cars”)

Optional Parameters:

Parameter	Type	Default	Description
`model_id`	`str`	`"Nomadic-VL-XLarge"`	AI model to use
`timeout`	`int`	`2400`	Analysis timeout in seconds
`wait_for_completion`	`bool`	`True`	Wait for analysis to complete
`return_subset`	`bool`	`False`	Return subset of results

Returns: Dict with video_id, mode, status, and hits containing search results.

my_videos()

Retrieve your uploaded videos, optionally filtered by folder.

# Get all videos
videos = client.my_videos()

# Get videos in specific folder
videos = client.my_videos(folder_id="my_folder")

Parameters:

Parameter	Type	Default	Description
`folder_id`	`str \| None`	`None`	Filter videos by folder name

Returns: List[Dict] with video information (video_id, filename, duration, size, etc.)

delete_video()

Remove a video by ID.

client.delete_video("video_id")

Parameters:

Parameter	Type	Description
`video_id`	`str`	ID of the video to delete (required)

Returns: Dict with deletion status

search_videos()

Search across your analysed videos in a folder using natural language queries.

results = client.search_videos(
    "red pickup truck overtaking",
    folder="my_folder"
)

Parameters:

Parameter	Type	Description
`query`	`str`	Natural language search query (required)
`folder`	`str`	Folder name to search within (required)

Returns: Dict with matches and summary fields

get_visuals()

Retrieve thumbnail URLs for all events in an analysis. If thumbnails don’t exist, they will be generated automatically.

# Get all thumbnail URLs from an analysis
visuals = client.get_visuals("video_id", "analysis_id")

# Returns list of thumbnail URLs
# ['https://storage.googleapis.com/.../event_0_thumb.jpg',
#  'https://storage.googleapis.com/.../event_1_thumb.jpg']

Parameters:

Parameter	Type	Description
`video_id`	`str`	ID of the video (required)
`analysis_id`	`str`	ID of the analysis containing events (required)

Returns: List[str] of thumbnail URLs with bounding box annotations

get_visual()

Retrieve a single thumbnail URL for a specific event in an analysis.

# Get thumbnail for the first event (index 0)
thumbnail_url = client.get_visual("video_id", "analysis_id", 0)

# Get thumbnail for the third event (index 2)
thumbnail_url = client.get_visual("video_id", "analysis_id", 2)

Parameters:

Parameter	Type	Description
`video_id`	`str`	ID of the video (required)
`analysis_id`	`str`	ID of the analysis containing events (required)
`event_idx`	`int`	0-based index of the event (required)

Returns: str - Single thumbnail URL Raises: ValueError if event index is out of range For a step-by-step tutorial, head over to SDK Usage Examples.

Getting Started

API Reference

Advanced

Legal

upload()

analyze()

RAPID_REVIEW Analysis

EDGE_CASE Analysis

SEARCH Analysis

my_videos()

delete_video()

search_videos()

get_visuals()

get_visual()

Getting Started

API Reference

Advanced

Legal

​upload()

​analyze()

​RAPID_REVIEW Analysis

​EDGE_CASE Analysis

​SEARCH Analysis

​my_videos()

​delete_video()

​search_videos()

​get_visuals()

​get_visual()

upload()

analyze()

RAPID_REVIEW Analysis

EDGE_CASE Analysis

SEARCH Analysis

my_videos()

delete_video()

search_videos()

get_visuals()

get_visual()