Using the SDK
For programmatic access to NomadicML, you can use our Python SDK.
1. Install the SDK
2. Initialize the Client
from nomadicml import NomadicML
import os
# Initialize with your API key
client = NomadicML(
api_key=os.environ.get("NOMADICML_API_KEY"),
base_url="https://api.nomadicml.com/" # Or your specific API endpoint
)
To get your API key, log in to the web platform, go to Profile > API Key, and generate a new key.
We recommend storing your API key in an environment variable for security.
3. Upload and Analyze Videos
The standard workflow involves uploading your videos first, then running analysis on them.
Uploads accept local paths or remote URLs that end with a common video extension (.mp4, .mov, .m4v, .mkv, .avi, .webm):
from nomadicml.video import AnalysisType
# First, upload your videos
single_result = client.upload("/path/to/video.mp4")
batch_result = client.upload([
"/path/to/video1.mp4",
"/path/to/video2.mp4",
])
#You can also upload remote URLs directly:
url_upload = client.upload("https://example.com/video1.mp4")
# You can upload videos to a specific folder for organization
folder_result = client.upload(
"/path/to/video.mp4",
folder="my-project-folder"
)
# Extract video IDs
video_id = single_result["video_id"]
video_ids = [result["video_id"] for result in batch_result]
# Then analyze them
analysis = client.analyze(video_id, analysis_type=AnalysisType.VIOLATION)
batch_analyses = client.analyze(video_ids, analysis_type=AnalysisType.VIOLATION)
4. Folder-Based Video Management
Organize your videos into folders for better project management:
# Upload videos to specific folders
client.upload("/path/to/video1.mp4", folder="dashcam-data")
client.upload([
"/path/to/video2.mp4",
"/path/to/video3.mp4"
], folder="test-scenarios")
# Analyze all videos in a folder
folder_analyses = client.analyze(
ids=None, # Don't specify video IDs
folder="dashcam-data",
analysis_type=AnalysisType.VIOLATION
)
# Get all videos in a specific folder
videos_in_folder = client.my_videos(folder_id="dashcam-data")
print(f"Found {len(videos_in_folder)} videos in folder")
5. Analysis Types
NomadicML supports four distinct analysis types, each optimized for different use cases. All analysis types can be run on a single video or a batch of videos.
Violation Detection (Default)
Detects traffic violations and safety issues in driving videos.
# Single video analysis
violation = client.analyze(
video_id,
analysis_type=AnalysisType.VIOLATION
)
# Batch analysis
violations = client.analyze(
video_ids, # List of video IDs ⇒ returns list of results
analysis_type=AnalysisType.VIOLATION
)
Edge Case Detection
Identifies unusual or edge case scenarios based on a specific category.
# Single video analysis
edge_case = client.analyze(
video_id,
analysis_type=AnalysisType.EDGE_CASE,
edge_case_category="autonomous-driving"
)
# Batch analysis
edge_cases = client.analyze(
video_ids, # Batch ⇒ list returned
analysis_type=AnalysisType.EDGE_CASE,
edge_case_category="autonomous-driving"
)
Search (Needle-in-Haystack)
Searches for specific events or objects within long videos using semantic search.
# Single video search
search = client.analyze(
video_id,
analysis_type=AnalysisType.SEARCH,
search_query="green crosswalk"
)
# Batch search across multiple videos
searches = client.analyze(
video_ids,
analysis_type=AnalysisType.SEARCH,
search_query="pedestrian crossing"
)
Rapid Review (Custom Event Detection)
Extracts custom events based on your specific requirements and categories.
# Single video rapid review
rapid = client.analyze(
video_id,
analysis_type=AnalysisType.RAPID_REVIEW,
custom_event="green crosswalk",
custom_category="environment"
)
# Batch rapid review
rapids = client.analyze(
video_ids,
analysis_type=AnalysisType.RAPID_REVIEW,
custom_event="vehicle overtaking",
custom_category="driving"
)
Analysis Parameters
| Parameter | Type | Required For | Description |
|---|
analysis_type | AnalysisType | All | The type of analysis to perform |
edge_case_category | str | EDGE_CASE | Category for edge case detection |
search_query | str | SEARCH | Query for semantic search |
custom_event | str | RAPID_REVIEW | Description of custom event to detect |
custom_category | str | RAPID_REVIEW | Category context for custom events |
folder | str | Optional | Folder name for organizing uploads or analyzing all videos in folder |
model_id | str | Optional | AI model to use (default: “Nomadic-VL-XLarge”) |
timeout | int | Optional | Analysis timeout in seconds (default: 2400) |
Explore this in more detail with our interactive Colab Notebook, which demonstrates custom event and category prompts, Use this when you want detailed analyses with category specific insights:
Needle-In-A-Haystack Mode: Ever scrubbed through an hour-long recording hunting for one short moment? This notebook shows how to surface those “needles” in seconds with NomadicML’s semantic video search. Use it if you want fast results, and don’t need detailed analysis but just event occurrences.
6. Search Across Multiple Videos
Search for specific content across all videos in a folder using semantic search. Videos are automatically pre-indexed for fast searching.
# Search across all videos in a folder
search_results = client.search_videos(
query="red trucks",
folder="dashcam-footage"
)
print(f"Found {len(search_results['matches'])} matches")
print(f"Summary: {search_results['summary']}")
Videos are automatically pre-indexed when uploaded, making search operations fast even across large video collections. The search uses semantic understanding, so queries like “red vehicles” will also match “crimson trucks” or “burgundy cars”.
7. Composite Workflow Example: Search + Analysis
Combine search with detailed analysis for powerful video intelligence workflows. This example shows how to find videos containing red trucks, then analyze those specific videos for car accidents.
from nomadicml.video import AnalysisType
# Step 1: Search for videos containing red trucks
print("🔍 Searching for videos with red trucks...")
search_results = client.search_videos(
query="red trucks",
folder="traffic-incidents"
)
# Step 2: Extract unique video IDs from search results
video_ids_with_red_trucks = list(set([
match['videoId'] for match in search_results['matches']
]))
print(f"📹 Found red trucks in {len(video_ids_with_red_trucks)} videos")
# Step 3: Run detailed accident analysis on those specific videos
print("\n🚨 Analyzing videos for car accidents...")
accident_analyses = client.analyze(
video_ids_with_red_trucks,
analysis_type=AnalysisType.RAPID_REVIEW,
custom_event="car accidents or collisions",
custom_category="driving"
)
Integrating with Cloud Storage (S3, GCS)
See Cloud Storage Uploads for instructions on generating secure pre‑signed URLs from AWS and Google Cloud.
For a concise listing of all video-related SDK functions, see Video Upload & Analysis.
