​
Video Operations

This page describes the main SDK methods for uploading videos and running analysis. The fastest path is upload_and_analyze, but you can also batch process URLs or re-run analysis on an existing upload.

For complete code walkthroughs, see SDK Usage Examples.

​
Available SDK Methods

  • upload_video – upload a file or URL without starting analysis
  • upload_and_analyze – upload and analyze in one step
  • upload_and_analyze_videos – batch upload multiple files or URLs
  • analyze_video – run a new analysis on an uploaded video
  • analyze_videos – analyze several uploaded videos at once

​
Response Structure

Successful calls to these methods return an UploadAnalyzeResponseSubset dataclass. It contains the uploaded video_id, basic metadata, and a list of detected events. The main fields look like this:

from nomadicml.types import UploadAnalyzeResponseSubset, VideoMetadataSubset,
    VisualAnalysisSubset, EventSubset

UploadAnalyzeResponseSubset(
    video_id="a7bca1938a8e4f",
    metadata=VideoMetadataSubset(
        filename="video.mp4",
        created_at="2025-05-30T19:32:51.444000+00:00",
        video_url="https://storage.googleapis.com/video.mp4",
        tag="default",
        duration_s=6,
        created_by_app="analysis",
        pre_summary="[...]",
        visual_analysis=VisualAnalysisSubset(
            model_id="Nomadic-VL-XLarge",
            events=[
                EventSubset(
                    description="...",
                    type="...",
                    recommendations="...",
                    aiAnalysis="...",
                    potentialViolations="...",
                    time="t=0.0s",
                    end_time="t=5.0s",
                    violationValidation="Not validated",
                    severity="high",
                )
            ],
        ),
    ),
    status="success",
)

This subset keeps the most relevant information while omitting fields used internally by the API.

​
upload_and_analyze

# Provide a local file path or cloud URL
result = client.video.upload_and_analyze(file_path="path/to/video.mp4")

# Or re-run analysis on a previously uploaded video ID
# result = client.video.upload_and_analyze(video_id="abc123")

The method supports three modes:

  • Standard analysis (default) – run the full driving analysis on a local file or direct URL.
  • Search mode – pass search_query="your search" to quickly scan the video for matching events.
  • Events only mode – provide custom_category and custom_event to generate event suggestions without the full analysis.

​
upload_and_analyze_videos

Process multiple files or URLs in parallel. This works well with pre-signed cloud storage URLs from services like AWS S3 or Google Cloud Storage.

urls = ["https://s3.amazonaws.com/bucket/video1.mp4", "https://storage.googleapis.com/bucket/video2.mp4"]
batch = client.video.upload_and_analyze_videos(urls, wait_for_completion=False)

Use wait_for_completion=True if you want to block until all analyses finish.

​
upload_video

Upload a video without starting analysis. Useful if you want to trigger analysis later.

upload_result = client.video.upload_video("path/to/video.mp4")
print(upload_result["video_id"])

​
analyze_video

If you already uploaded a video earlier you can trigger a new analysis by ID:

client.video.analyze_video(video_id)

This is useful when new models are released or if you changed your analysis settings.

​
analyze_videos

Run analysis on several previously uploaded videos:

ids = ["abc123", "def456"]
client.video.analyze_videos(ids)

For a step-by-step tutorial, head over to SDK Usage Examples.