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 a Video
The standard way to upload and analyze a video is using the upload_and_analyze method:
result = client.video.upload_and_analyze("path/to/your/video.mp4")
print(results)
>> UploadAnalyzeResponseSubset(
>> video_id="a7bca1938a8e4f",
>> metadata=VideoMetadataSubset(
>> video_id="a7bca1938a8e4f",
>> title="your_video_title",
>> created_at="2025-05-30T19:32:51.444000+00:00",
>> video_url="https://storage.googleapis.com/your_video_url.mp4",
>> tag="default",
>> visual_analysis=VisualAnalysisSubset(
>> model_id="Nomadic-VL-XLarge",
>> events=[
>> EventSubset(
>> description="[Detection] Example Event Description",
>> type="Example Event Type",
>> recommendations="Example recommendations.",
>> aiAnalysis='{"SUMMARY": "Example AI summary."}',
>> potentialViolations="Example Violation",
>> time="t=0.0s",
>> end_time="t=5.0s",
>> violationValidation="Not validated",
>> severity="high",
>> )
>> ],
>> ),
>> filename="your_video.mp4",
>> duration_s=6,
>> created_by_app="analysis",
>> pre_summary='[{"start_time": 0.0, "end_time": 6.0, "description": "Example pre-summary."}]',
>> chunks_uploaded=1,
>> ),
>> status="success",
>> )
Using Custom Event and Category Prompts
You can also guide the analysis by providing a custom_category and a custom_event prompt. This is useful for focusing the AI on specific types of events or scenarios within your video.
# Example with custom category and event
custom_analysis_result = client.video.upload_and_analyze(
file_path="/path/to/your/video.mp4", # Replace with your actual file path
custom_category="Driving",
custom_event="Find all events of overtaking cars"
)
print(custom_analysis_result)
Parameters:
custom_category (optional, str): Specifies the general domain of the video content.
- Accepted values:
"Driving", "Aerial", "Security", "Environment".
custom_event (optional, str): A natural language prompt describing the specific event(s) you want the AI to find.
If both custom_category and custom_event are None (or not provided), the analysis defaults to a general “driving violation” detection mode.
Output Format (with custom_category and custom_event):
When using custom_category and custom_event, the upload_and_analyze method returns a dictionary with the following structure:
{
"video_id": "30fcf35fb5b442059bbc756f08ffcf79",
"events": {
"status": "success",
"answer": "Yes, I can help you identify overtaking car events in this video. There is one clear instance of a car overtaking the ego vehicle.\n\nAt 00:01, a white pickup truck begins to overtake your vehicle from the adjacent left lane. By 00:03, the truck has fully passed your vehicle. This was a smooth overtake, as your vehicle maintained its lane and speed, and the truck completed the maneuver with ample space, indicating a low severity level regarding potential safety impact.",
"suggested_events": [
{
"label": "Vehicle Overtake",
"severity": "LOW",
"t_start": "00:01",
"t_end": "00:03",
"category": "Driving Maneuver",
"confidence": 1.0,
"aiAnalysis": "A white pickup truck in the adjacent left lane begins to overtake the ego vehicle at 00:01 and completes the overtake by 00:03. The ego vehicle maintains its lane and speed, and the overtaking maneuver is performed smoothly with sufficient clearance from the ego vehicle, resulting in a low safety impact."
}
],
"processing_time": 5.843569056130946,
"prompt_type": "visual_qa"
},
"mode": "events_only"
}
Explore this in more detail with our interactive Colab Notebook, which demonstrates custom event and category prompts:
