Scopix

Documentation

Video Types

Types for video upload, analysis, and scene operations

Enums

VideoUploadStatus

Status of a video upload

python
class VideoUploadStatus(str, Enum):
    UPLOADING   = "uploading"
    PROCESSING  = "processing"
    COMPLETED   = "completed"
    FAILED      = "failed"
    ABORTED     = "aborted"

VideoAnalysisStatus

Status of a video analysis job

python
class VideoAnalysisStatus(str, Enum):
    PENDING          = "pending"
    UPLOADING_TO_VLM = "uploading_to_vlm"
    PROCESSING       = "processing"
    COMPLETED        = "completed"
    FAILED           = "failed"
    CANCELLED        = "cancelled"

Metadata Types

VideoMetadata

Technical metadata extracted from the video file by ffprobe during the variant-generation step. Populated onto the file record's video_metadata field and surfaced on the API's get_processing_status response within seconds of upload completing.

python
@dataclass(frozen=True)
class VideoMetadata:
    duration_seconds: Optional[float]  # Video duration
    resolution: Optional[str]          # e.g. "1920x1080"
    width: Optional[int]
    height: Optional[int]
    frame_rate: Optional[float]        # Frames per second
    video_codec: Optional[str]         # e.g. "h264"
    audio_codec: Optional[str]         # None if video has no audio track
    bitrate_kbps: Optional[int]
    file_size_bytes: Optional[int]
    format_name: Optional[str]         # Container format, e.g. "mp4"

Analysis Types

VideoAnalysisJobStatus

Status of an analysis job, returned by get_status(), get_status_by_media(), and wait_for_completion()

python
@dataclass(frozen=True)
class VideoAnalysisJobStatus:
    analysis_job_id: str
    media_id: str
    status: str                              # "pending" | "processing" | "completed" | "failed" | "cancelled"
    progress_percent: float = 0.0            # 0.0–100.0
    current_step: Optional[str] = None       # Human-readable current processing step
    started_at: Optional[datetime] = None
    completed_at: Optional[datetime] = None
    error_message: Optional[str] = None
    error_code: Optional[str] = None
    retry_count: int = 0
    max_retries: int = 3
    estimated_completion_time: Optional[datetime] = None


    # Properties
    @property
    def is_completed(self) -> bool: ...  # status == "completed"
    @property
    def is_failed(self) -> bool: ...     # status == "failed"
    @property
    def is_pending(self) -> bool: ...    # status == "pending"
    @property
    def is_terminal(self) -> bool: ...   # completed | failed | cancelled

VideoAnalysisQueueResult

Result of queuing a video for analysis, returned by queue()

python
@dataclass(frozen=True)
class VideoAnalysisQueueResult:
    analysis_job_id: str
    media_id: str
    queue_position: Optional[int] = None
    estimated_start_time: Optional[datetime] = None
    message: Optional[str] = None

VideoAnalysisRetryResult

Result of retrying a failed analysis job, returned by retry()

python
@dataclass(frozen=True)
class VideoAnalysisRetryResult:
    analysis_job_id: str
    media_id: str
    status: str = "pending"
    retry_count: int = 0
    max_retries: int = 3
    message: Optional[str] = None

Scene Types

VideoSceneList

Container returned by video_scenes.list()

python
@dataclass(frozen=True)
class VideoSceneList:
    items: list[VideoScene]           # Extracted scenes, ordered by scene_index
    total_count: int = 0
    video_id: Optional[str] = None

VideoScene

A single scene extracted from a video during analysis

python
@dataclass(frozen=True)
class VideoScene:
    scene_id: str
    scene_index: int = 0               # Zero-based index within the video
    start_time: float = 0.0            # Seconds from start of video
    end_time: float = 0.0              # Seconds from start of video
    time_range_formatted: Optional[str] = None  # e.g. "00:01:30-00:02:15"
    description: Optional[str] = None  # AI-generated scene description
    tags: list[str] = field(default_factory=list)
    visible_text: Optional[str] = None  # OCR text detected in scene
    confidence_score: Optional[float] = None
    embedding_status: Optional[str] = None    # Search indexing status
    thumbnail_url: Optional[str] = None      # URL path for scene thumbnail
    created_at: Optional[datetime] = None

Related

FilesResource

Unified upload entry point for video, image, and document files

VideoAnalysisResource

queue(), wait_for_completion(), get_status()

Callback Types

VideoChunkProgressEvent, VideoUploadCompleteEvent, VideoAnalysisProgressEvent