Scopix

Documentation

VideoScenesResource

Access via client.video_scenes

Prerequisite

Scenes are extracted during AI video analysis. Call wait_for_completion() before listing scenes to ensure analysis has finished.

Methods

list()

List all scenes for a video, ordered by scene index

python
async def list(video_id: str) -> VideoSceneList
Returns: VideoSceneList — Contains scenes list and count. Returns count=0 if no scenes exist.
Raises ResourceNotFoundError if the video is not found

Example

python
from scopix import Scopix


async with Scopix(api_key="scopix_...") as client:
    # Upload and wait for the full video pipeline to finish
    result = await client.files.upload("inspection.mp4")
    await client.files.wait_for_session(result.image_id, timeout=600)


    # List extracted scenes
    scene_list = await client.video_scenes.list(result.image_id)
    print(f"Found {scene_list.total_count} scenes")
    for scene in scene_list.items:
        print(f"Scene {scene.scene_index}: {scene.time_range_formatted}")
        print(f"  {scene.description}")
        if scene.tags:
            print(f"  Tags: {', '.join(scene.tags)}")

get_thumbnail()

Download the thumbnail image for a scene. Thumbnails are JPEG images captured at the scene midpoint during analysis.

python
async def get_thumbnail(scene_id: str) -> bytes
Returns: Raw JPEG bytes
Raises ResourceNotFoundError if the scene or thumbnail is not found

Example — Save scene thumbnails to disk

python
async with Scopix(api_key="scopix_...") as client:
    scene_list = await client.video_scenes.list(media_id)


    for scene in scene_list.items:
        if scene.thumbnail_url:
            image_bytes = await client.video_scenes.get_thumbnail(scene.scene_id)
            filename = f"scene_{scene.scene_index:03d}.jpg"
            with open(filename, "wb") as f:
                f.write(image_bytes)
            print(f"Saved {filename}")

Sync Client

Both methods are available on SyncScopix via client.video_scenes with identical signatures (no await).

python
from scopix import SyncScopix


with SyncScopix(api_key="scopix_...") as client:
    scenes = client.video_scenes.list(media_id)
    thumbnail = client.video_scenes.get_thumbnail(scenes.items[0].scene_id)

Related

VideoAnalysisResource

Wait for analysis to complete before listing scenes

Video Types

VideoScene, VideoSceneList

Uploading Videos

End-to-end walkthrough of the video ingest pipeline