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")
ParameterTypeDefaultDescription
videosstr | Path | Sequence[str | Path]NoneSingle file/URL or list of files/URLs (required)
edge_case_categorystrNoneRoutes to edge case upload pipeline
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 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"
)
ParameterTypeDefaultDescription
idsstr | Sequence[str]NoneVideo ID(s) to analyze
analysis_typeAnalysisTypeNoneType of analysis to perform
model_idstr"Nomadic-VL-XLarge"AI model to use
timeoutint2400Analysis timeout in seconds
wait_for_completionboolTrueWait for analysis to complete
folderstrNoneAnalyze all videos in folder (mutually exclusive with ids)

Returns: Dict (single) or List[Dict] (multiple) with analysis results

For RAPID_REVIEW with is_thumbnail=True, each event in the response will include an annotated_thumbnail_url field containing a link to the generated thumbnail with bounding box annotations.

AnalysisTypeWhat it doesRequired extra parametersOptional extra parameters
AnalysisType.RAPID_REVIEWRapid Review: “find-this-event” detectioncustom_event: str
custom_category: CustomCategory | str		is_thumbnail: bool = False
AnalysisType.EDGE_CASESpecialized edge-case detectionedge_case_category: strconcept_ids: List[str]
mode: str = "assistant"
AnalysisType.SEARCHSemantic search within long videossearch_query: str

nomadicml.video.CustomCategory

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

​
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_idstrNoneFilter 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:

ParameterTypeDefaultDescription
video_idstrNoneID of the video to delete (required)

Returns: Dict with deletion status

​
search_videos()

Search across videos in a folder using natural language queries.

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

Parameters:

ParameterTypeDefaultDescription
querystrNoneNatural language search query (required)
folderstrNoneFolder name to search within (required)
reasoning_trace_pathstrNonePath for reasoning trace

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:

ParameterTypeDefaultDescription
video_idstrNoneID of the video (required)
analysis_idstrNoneID 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:

ParameterTypeDefaultDescription
video_idstrNoneID of the video (required)
analysis_idstrNoneID of the analysis containing events (required)
event_idxintNone0-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.