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:
ParameterTypeDescription
videosstr | Path | Sequence[str | Path]Single file/URL or list of files/URLs
Optional Parameters:
ParameterTypeDefaultDescription
folderstrNoneFolder name for organizing uploads
upload_timeoutint1200Timeout in seconds for upload completion
wait_for_uploadedboolTrueWait 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 2 analysis types

# Ask: Custom event detection (works for all video lengths)
client.analyze("abc123", 
    analysis_type=AnalysisType.ASK,
    custom_event="green crosswalk",
    custom_category=CustomCategory.DRIVING
)

# With thumbnail generation (creates annotated bounding box thumbnails)
client.analyze("abc123", 
    analysis_type=AnalysisType.ASK,
    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"
)

​
ASK Analysis

Detect custom events in videos using natural language descriptions. Perfect for finding specific scenarios like “green crosswalk” or “yellow taxi”. Works for all video lengths, including long videos, with fast results. Required Parameters:
ParameterTypeDescription
id(s) or folderstr | Sequence[str]Video ID(s) or folder name (use one, not both)
analysis_typeAnalysisTypeMust be AnalysisType.ASK
custom_eventstrEvent description to detect (e.g., “green crosswalk”)
custom_categoryCustomCategory | strCategory context (e.g., CustomCategory.DRIVING)
nomadicml.video.CustomCategory
  • CustomCategory.DRIVING
  • CustomCategory.ROBOTICS
  • CustomCategory.AERIAL
  • CustomCategory.SECURITY
  • CustomCategory.ENVIRONMENT
Optional Parameters:
ParameterTypeDefaultDescription
model_idstr"Nomadic-VL-XLarge"AI model to use
timeoutint2400Analysis timeout in seconds
wait_for_completionboolTrueWait for analysis to complete
is_thumbnailboolFalseGenerate annotated bounding box thumbnails
return_subsetboolFalseReturn 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:
ParameterTypeDescription
ids or folderstr | Sequence[str]Video ID(s) or folder name (use one, not both)
analysis_typeAnalysisTypeMust be AnalysisType.EDGE_CASE
edge_case_categorystrEdge case category (e.g., “infrastructure-monitoring”)
Optional Parameters:
ParameterTypeDefaultDescription
model_idstr"Nomadic-VL-XLarge"AI model to use
timeoutint2400Analysis timeout in seconds
wait_for_completionboolTrueWait for analysis to complete
concept_idsList[str]NoneConcept IDs for specialized detection
modestr"assistant"Analysis mode: “assistant” or “agent”
return_subsetboolFalseReturn subset of results
Returns: Dict with video_id, analysis_id, mode, status, and events.

​
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:
ParameterTypeDefaultDescription
folder_idstr | NoneNoneFilter 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:
ParameterTypeDescription
video_idstrID 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:
ParameterTypeDescription
querystrNatural language search query (required)
folderstrFolder 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:
ParameterTypeDescription
video_idstrID of the video (required)
analysis_idstrID 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:
ParameterTypeDescription
video_idstrID of the video (required)
analysis_idstrID of the analysis containing events (required)
event_idxint0-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.