​
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"
)

# Upload from YouTube
result = client.video.upload_video(
    source="youtube",
    youtube_url="https://www.youtube.com/watch?v=VIDEO_ID"
)

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

​
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”, “youtube”, or “saved”)
  • file (file, required for “file” source): The video file to upload
  • youtube_url (string, required for “youtube” source): YouTube URL to process
  • video_id (string, required for “saved” source): ID of an existing video
  • created_by (string, optional): User identifier for tracking

Response:

{
  "video_id": "uuid-string",
  "status": "uploading",
  "message": "Video upload initiated"
}

​
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"
)

​
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

Response:

{
  "video_id": "uuid-string",
  "status": "processing",
  "message": "Video 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
)

​
HTTP Request

This is a convenience method in the SDK that combines the upload and analyze endpoints. There is no direct equivalent in the REST API - you would need to call the upload endpoint and then the analyze endpoint.

​
Video Status

Check the status of a video upload and analysis.

​
SDK Method

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

​
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”)

Response:

{
  "video_id": "uuid-string",
  "status": "completed",
  "metadata": {
    "filename": "example.mp4",
    "upload_time": "2025-03-15T14:30:00Z",
    "duration": 120.5,
    "frame_count": 3615,
    "fps": 30.0,
    "width": 1920,
    "height": 1080,
    "visual_analysis": {
      "status": "completed",
      "progress": 100,
      "event_count": 5
    }
  }
}

​
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
)

​
HTTP Request

This is a convenience method in the SDK. There is no direct equivalent in the REST API - you would need to poll the status endpoint until the analysis is complete.

​
Video Analysis Results

Get the complete analysis results for a video.

​
SDK Method

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

​
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”)

Response:

{
  "video_id": "uuid-string",
  "status": "completed",
  "filename": "example.mp4",
  "upload_time": "2025-03-15T14:30:00Z",
  "metadata": {
    "duration": 120.5,
    "frame_count": 3615,
    "fps": 30.0,
    "width": 1920,
    "height": 1080,
    "source": "file",
    "original_url": null,
    "title": "Example Video"
  },
  "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
  }
}

​
Video Events

Get just the events detected in a video.

​
SDK Method

# Get all events
events = client.video.get_video_events("video_id")

# Filter events by severity
high_severity_events = client.video.get_video_events(
    video_id="video_id",
    severity="high"
)

# Filter events by type
traffic_violations = client.video.get_video_events(
    video_id="video_id",
    event_type="Traffic Violation"
)

​
HTTP Request

GET /api/video/{video_id}/events

Headers:

X-API-Key: your_api_key

Query Parameters:

  • firebase_collection_name (string, required): Collection name (default: “videos”)
  • severity (string, optional): Filter by severity (“low”, “medium”, “high”)
  • event_type (string, optional): Filter by event type (“Traffic Violation”, “Safety Alert”, etc.)

Response:

[
  {
    "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...
]

​
Stream Video

Stream a video file.

​
SDK Method

The SDK doesn’t provide a direct method for streaming video content, as this is typically handled by the frontend application.

​
HTTP Request

GET /api/videos/{video_id}/stream

Headers:

X-API-Key: your_api_key

Response: Binary video data with appropriate content type and streaming headers.

​
Error Handling

The API returns standard HTTP status codes:

  • 200 OK: Request succeeded
  • 400 Bad Request: Invalid input parameters
  • 401 Unauthorized: Invalid or missing API key
  • 403 Forbidden: Valid API key but insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Error responses include a JSON body with details:

{
  "error": true,
  "code": "error_code",
  "message": "Human-readable error message",
  "details": {
    // Additional error details if available
  }
}

In the SDK, errors are raised as exceptions:

  • AuthenticationError: Authentication issues
  • 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

​
Rate Limits

The API has the following rate limits:

  • Uploads: 10 per minute, 100 per day
  • API Calls: 60 per minute, 10,000 per day

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1616979600

​
Next Steps

Analysis API

Learn about analysis-specific endpoints

Events API

Work with the events API