Video API

The Video API allows you to programmatically upload, manage, and process videos. This page documents both the REST API endpoints and the corresponding SDK methods.

Video Upload

Upload a new video for analysis.

SDK Method

# Upload from a local file
result = client.video.upload_video(
    source="file",
    file_path="/path/to/video.mp4"
)

# Reprocess a saved video
result = client.video.upload_video(
    source="saved",
    video_id="existing_video_id"
)

Method Parameters

Parameter	Type	Required	Description
`source`	string	Yes	Source type: “file”, or “saved”
`file_path`	string	For “file” source	Path to the local video file
`video_id`	string	For “saved” source	ID of an existing video
`created_by`	string	No	User identifier for tracking

Return Value

{
  "video_id": "uuid-string",
  "status": "success",
  "message": "Video uploaded successfully"
}

HTTP Request

POST /api/upload-video

Headers:

X-API-Key: your_api_key
Content-Type: multipart/form-data  # for file uploads

Form Parameters:

firebase_collection_name (string, required): Collection name for storage (default: “videos”)
source (string, required): Source type (“file”, or “saved”)
file (file, required for “file” source): The video file to upload
video_id (string, required for “saved” source): ID of an existing video
created_by (string, optional): User identifier for tracking

Video Analysis

Start analysis for an uploaded video.

SDK Method

# Start analysis for a specific video
result = client.video.analyze_video("video_id")

# Start analysis with custom user identifier
result = client.video.analyze_video(
    video_id="video_id",
    created_by="user123",
    model_id="Nomadic-VL-XLarge"  # Specify model type
)

Method Parameters

Parameter	Type	Required	Description
`video_id`	string	Yes	ID of the video to analyze
`created_by`	string	No	User identifier for tracking
`model_id`	string	No	Model to use (default: “Nomadic-VL-XLarge”)

Return Value

{
  "video_id": "uuid-string",
  "status": "success",
  "message": "Analysis started"
}

HTTP Request

POST /api/analyze-video/{video_id}

Headers:

X-API-Key: your_api_key
Content-Type: application/x-www-form-urlencoded

Form Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)
created_by (string, optional): User identifier for tracking
model_id (string, optional): Model to use for analysis

Batch Analysis

Process multiple videos at once.

SDK Method

# Analyze multiple videos
results = client.video.analyze_videos([
    "video_id_1", 
    "video_id_2", 
    "video_id_3"
])

# Upload and analyze multiple videos
batch_results = client.video.upload_and_analyze_videos(
    ["/path/to/video1.mp4", "/path/to/video2.mp4"], 
    wait_for_completion=False
)

Method Parameters

Parameter	Type	Required	Description
`video_ids`	list	Yes	List of video IDs to analyze
`created_by`	string	No	User identifier for tracking
`model_id`	string	No	Model to use (default: “Nomadic-VL-XLarge”)

Return Value

[
  {
    "video_id": "uuid-string-1",
    "status": "success",
    "message": "Analysis started"
  },
  {
    "video_id": "uuid-string-2",
    "status": "success",
    "message": "Analysis started"
  }
]

Upload and Analyze

Upload a video and start analysis in a single operation.

SDK Method

# Upload and analyze a video
result = client.video.upload_and_analyze(
    file_path="/path/to/video.mp4", 
    wait_for_completion=True,
    timeout=600
)

Method Parameters

Parameter	Type	Required	Description
`file_path`	string	Yes	Path to the video file
`wait_for_completion`	boolean	No	Wait for analysis to complete (default: True)
`timeout`	integer	No	Maximum wait time in seconds (default: 600)
`created_by`	string	No	User identifier for tracking
`model_id`	string	No	Model to use (default: “Nomadic-VL-XLarge”)

Return Value

If wait_for_completion is True:

{
  "video_id": "uuid-string",
  "status": "completed",
  "metadata": { ... },
  "events": [ ... ],
  "analysis": { ... }
}

If wait_for_completion is False:

{
  "video_id": "uuid-string",
  "status": "processing",
  "message": "Video uploaded and analysis started"
}

Video Status

Check the status of a video upload and analysis.

SDK Method

# Get video status
status = client.video.get_video_status("video_id")

Method Parameters

Parameter	Type	Required	Description
`video_id`	string	Yes	ID of the video

Return Value

{
  "status": "completed",
  "video_id": "uuid-string",
  "quick_summary": {
    "status": "completed",
    "progress": 100,
    "events": [
      {
        "time": 23.5,
        "type": "Traffic Violation",
        "severity": "medium",
        "description": "Running stop sign"
      },
      // More events...
    ]
  },
  "metadata": {
    "filename": "example.mp4",
    "upload_time": "2023-03-15T14:30:00Z",
    "duration": 120.5,
    "frame_count": 3615,
    "fps": 30.0,
    "width": 1920,
    "height": 1080
  }
}

HTTP Request

GET /api/video/{video_id}/status

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)

Wait for Analysis

Wait for video analysis to complete.

SDK Method

# Wait for analysis to complete with custom parameters
status = client.video.wait_for_analysis(
    video_id="video_id",
    timeout=600,  # Maximum wait time in seconds
    poll_interval=5  # Time between status checks in seconds
)

# Wait for multiple analyses to complete
results = client.video.wait_for_analyses(
    video_ids=["video_id_1", "video_id_2"]
)

Method Parameters

Parameter	Type	Required	Description
`video_id`	string	Yes	ID of the video
`timeout`	integer	No	Maximum wait time in seconds (default: 600)
`poll_interval`	integer	No	Time between status checks in seconds (default: 5)

Return Value

The final status object once analysis completes:

{
  "status": "completed",
  "video_id": "uuid-string",
  "quick_summary": { ... },
  "metadata": { ... }
}

Video Analysis Results

Get the complete analysis results for a video.

SDK Method

# Get complete analysis
analysis = client.video.get_video_analysis("video_id")

Method Parameters

Parameter	Type	Required	Description
`video_id`	string	Yes	ID of the video

Return Value

{
  "video_id": "uuid-string",
  "status": "completed",
  "filename": "example.mp4",
  "upload_time": "2023-03-15T14:30:00Z",
  "metadata": {
    "duration": 120.5,
    "frame_count": 3615,
    "fps": 30.0,
    "width": 1920,
    "height": 1080
  },
  "events": [
    {
      "time": 23.5,
      "type": "Traffic Violation",
      "severity": "medium",
      "description": "Running stop sign",
      "dmv_rule": "CVC 22450(a)",
      "metrics": {
        "confidence": 0.92,
        "speed": 15.7
      },
      "ai_analysis": "Vehicle approached stop sign at intersection and continued through without coming to a complete stop...",
      "recommendations": "Always come to a complete stop at stop signs, even if the intersection appears clear..."
    },
    // Additional events...
  ],
  "analysis": {
    "summary": "This video contains 5 notable events including 2 traffic violations...",
    "safety_score": 78,
    "dmv_compliance_score": 82
  }
}

HTTP Request

GET /api/video/{video_id}/analysis

Headers:

X-API-Key: your_api_key

Query Parameters:

firebase_collection_name (string, required): Collection name (default: “videos”)

Multiple Video Analyses

Get analysis results for multiple videos.

SDK Method

# Get analyses for multiple videos
analyses = client.video.get_video_analyses([
    "video_id_1", 
    "video_id_2"
])

Method Parameters

Parameter	Type	Required	Description
`video_ids`	list	Yes	List of video IDs

Return Value

[
  {
    "video_id": "video_id_1",
    "metadata": { ... },
    "events": [ ... ],
    "status": "success"
  },
  {
    "video_id": "video_id_2",
    "metadata": { ... },
    "events": [ ... ],
    "status": "success"
  }
]

Error Handling

The API returns standard HTTP status codes and the SDK raises specific exceptions:

AuthenticationError: Invalid or missing API key
VideoUploadError: Problems with video upload
AnalysisError: Issues during video analysis
ValidationError: Invalid input parameters
APIError: General API errors
NomadicMLError: Base class for all SDK errors

Example:

from nomadicml.exceptions import (
    AuthenticationError,
    VideoUploadError,
    AnalysisError,
    NomadicMLError
)

try:
    client.video.upload_and_analyze("path/to/video.mp4")
except AuthenticationError:
    print("Authentication failed - check your API key")
except VideoUploadError as e:
    print(f"Upload failed: {e}")
except AnalysisError as e:
    print(f"Analysis failed: {e}")
except NomadicMLError as e:
    print(f"An error occurred: {e}")

API Reference

​Video API

​Video Upload

​SDK Method

​Method Parameters

​Return Value

​HTTP Request

​Video Analysis

​SDK Method

​Method Parameters

​Return Value

​HTTP Request

​Batch Analysis

​SDK Method

​Method Parameters

​Return Value

​Upload and Analyze

​SDK Method

​Method Parameters

​Return Value

​Video Status

​SDK Method

​Method Parameters

​Return Value

​HTTP Request

​Wait for Analysis

​SDK Method

​Method Parameters

​Return Value

​Video Analysis Results

​SDK Method

​Method Parameters

​Return Value

​HTTP Request

​Multiple Video Analyses

​SDK Method

​Method Parameters

​Return Value

​Error Handling

​Next Steps

Analysis API

Events API

Video API

Video Upload

SDK Method

Method Parameters

Return Value

HTTP Request

Video Analysis

SDK Method

Method Parameters

Return Value

HTTP Request

Batch Analysis

SDK Method

Method Parameters

Return Value

Upload and Analyze

SDK Method

Method Parameters

Return Value

Video Status

SDK Method

Method Parameters

Return Value

HTTP Request

Wait for Analysis

SDK Method

Method Parameters

Return Value

Video Analysis Results

SDK Method

Method Parameters

Return Value

HTTP Request

Multiple Video Analyses

SDK Method

Method Parameters

Return Value

Error Handling

Next Steps