Scopix

Documentation

VideoAnalysisResource

Access via client.video_analysis

When is this needed?

Analysis is queued automatically by the server as soon as an uploaded file is detected as video — you do not need to call queue() for a freshly uploaded video. Use this resource to monitor progress, wait for completion, retry a failed job, or re-queue a video whose analysis was skipped (for example, due to insufficient credits at upload time).

Methods

wait_for_completion()

Poll until analysis completes or fails, with exponential backoff

python
async def wait_for_completion(
    analysis_job_id: str,
    *,
    timeout: Optional[float] = None,                              # Default: config polling_timeout
    on_progress: Optional[Callable[[VideoAnalysisJobStatus], None]] = None,
) -> VideoAnalysisJobStatus
Returns: VideoAnalysisJobStatus — Final status with is_completed=True
Raises: VideoAnalysisError if analysis fails, ScopixTimeoutError if timeout is exceeded

Example

python
from scopix import Scopix


async with Scopix(api_key="scopix_...") as client:
    # Upload returns the file ID; analysis is queued server-side.
    result = await client.files.upload("video.mp4")


    # Look up the analysis job by media ID
    job = await client.video_analysis.get_status_by_media(result.image_id)


    def on_progress(status):
        print(f"Analysis: {status.progress_percent:.0f}% — {status.current_step}")


    final = await client.video_analysis.wait_for_completion(
        job.analysis_job_id,
        timeout=600.0,
        on_progress=on_progress,
    )
    print(f"Done: {final.status}")

get_status()

Get the current status of an analysis job by its job ID

python
async def get_status(analysis_job_id: str) -> VideoAnalysisJobStatus
Returns: VideoAnalysisJobStatus
Raises ResourceNotFoundError if the job is not found

get_status_by_media()

Get the analysis status for a video using its media ID

python
async def get_status_by_media(media_id: str) -> VideoAnalysisJobStatus
Returns: VideoAnalysisJobStatus
Raises ResourceNotFoundError if the video or job is not found

queue()

Queue analysis for an already-uploaded video. Typically only needed when the initial auto-queue was skipped — for example, when the tenant was out of credits at upload time.

python
async def queue(
    media_id: str,
    *,
    analysis_type: str = "full_vlm",   # "full_vlm" | "frame_sample" | "scene_detection" | "transcript"
    priority: str = "normal",          # "normal" | "high"
) -> VideoAnalysisQueueResult
Returns: VideoAnalysisQueueResult — Contains analysis_job_id and queue_position

Example — Re-queue a video whose initial analysis was skipped

python
async with Scopix(api_key="scopix_...") as client:
    file = await client.files.get(media_id)


    if file.analysis_skipped:
        queue_result = await client.video_analysis.queue(
            media_id,
            analysis_type="full_vlm",
        )
        final = await client.video_analysis.wait_for_completion(
            queue_result.analysis_job_id,
        )
        print(f"Analysis finished: {final.status}")

retry()

Retry a failed analysis job

python
async def retry(
    analysis_job_id: str,
    media_id: str,
    *,
    reason: Optional[str] = None,
) -> VideoAnalysisRetryResult
Returns: VideoAnalysisRetryResult — Contains new job status and retry_count

Sync Client

All methods are available on SyncScopix via client.video_analysis with identical signatures (no await).

python
from scopix import SyncScopix


with SyncScopix(api_key="scopix_...") as client:
    status = client.video_analysis.get_status(job_id)
    print(f"Progress: {status.progress_percent:.0f}%")

Related

FilesResource

Unified upload entry — videos use the same client.files.upload() path as images

VideoScenesResource

List scenes and download thumbnails after analysis

Video Types

VideoAnalysisJobStatus, VideoAnalysisQueueResult, VideoAnalysisRetryResult