Python SDK

Installation

pip install videovector

Connect server-side workflow services

from videovector import VideoVector

with VideoVector(api_key="sk_live_...") as client:
    indexes = client.indexes.list()

Manage operator-controlled API keys

Use bearer auth for JWT-only endpoints such as client.api_keys.*.

from videovector import VideoVector

with VideoVector(bearer_token="eyJ...") as client:
    key = client.api_keys.create(name="SDK key", scopes=["read", "search"])

Configure reusable service environments

The SDK configuration layer reads:

• VIDEO_VECTOR_API_KEY
• VIDEO_VECTOR_BEARER_TOKEN
• VIDEO_VECTOR_AUTH_MODE
• VIDEO_VECTOR_BASE_URL
• VIDEO_VECTOR_TIMEOUT
• VIDEO_VECTOR_MAX_RETRIES

from videovector import VideoVector

with VideoVector() as client:
    results = client.search.text(index_id="idx_archive", query="station entrance")

Tune client behavior for long media jobs

The default base URL is https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2.

client = VideoVector(
    api_key="sk_live_...",
    base_url="https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2",
    timeout=90,
    max_retries=5,
)

Protect prompt-run and automation writes

The HTTP client automatically retries:

• idempotent methods such as GET, PUT, and DELETE
• any request that includes an explicit idempotency_key

For non-idempotent POST requests, pass an idempotency key when a retry should be safe.

run = client.prompt_runs.execute(
    prompt_id="prompt_scene_extract",
    target={"type": "index", "index_id": "idx_archive"},
    idempotency_key="prompt-run-archive-2026-04-20",
)

The same pattern applies to:

• client.indexes.create
• client.prompts.create
• client.prompts.update
• client.connectors.create_s3
• client.import_jobs.create
• client.exports.create_index_export
• client.webhooks.create

Iterate through media collections

Paginated endpoints return SyncPage[T] or AsyncPage[T].

page = client.indexes.list_videos("idx_archive", limit=50)
for video in page.auto_paging_iter():
    print(video.video_id)

REST-only helper surfaces

The parity matrix explicitly calls out public endpoints that are not wrapped by the SDK, including:

• /mcp/*
• /processing/events/stream
• /videos/{video_id}/gif
• /videos/segments/{segment_id}/thumbnail

Use the REST API directly for those helper or MCP-specific surfaces.

Create a prompt and execute it on an index

from videovector import VideoVector

with VideoVector(api_key="sk_live_...") as client:
    prompt = client.prompts.create(
        name="Scene extractor",
        prompt_text="Extract structured scene evidence from this segment.",
        json_schema={
            "type": "object",
            "properties": {
                "headline": {"type": "string"},
                "scene": {
                    "type": "object",
                    "properties": {
                        "location": {"type": "string"},
                    },
                },
            },
        },
        video_level={
            "instructions_text": "Summarize the entire asset.",
            "included_segment_fields": ["headline", "scene.location", "transcription"],
            "json_schema": {
                "type": "object",
                "properties": {"program_summary": {"type": "string"}},
            },
        },
    )

    run = client.prompt_runs.execute(
        prompt_id=prompt.prompt_id,
        target={"type": "index", "index_id": "idx_archive"},
        video_segmentation_type="smart",
        processing_model="gemini-2.5-flash",
        idempotency_key="run-archive-2026-04-20",
    )

    run = client.prompt_runs.wait_for_completion(run.run_id)

Retrieve segment and video-level results

segment_page = client.prompt_runs.list_results(run.run_id, video_id="vid_456", limit=50)
video_result = client.prompt_runs.get_video_result(run.run_id, "vid_456")

Search by text, image, and filters

results = client.search.text(
    index_id="idx_archive",
    query="reporter outside a station entrance",
    run_ids=[run.run_id],
)

filtered = client.search.filter(
    index_id="idx_archive",
    run_ids=[run.run_id],
    conditions=[
        {
            "field": "scene.people[].emotion",
            "operator": "equals",
            "value": "happy",
            "type": "string",
        }
    ],
)

Configure connectors and launch an import job

connector = client.connectors.create_s3(
    name="Archive S3",
    bucket="media-archive",
    region="us-east-1",
    aws_access_key_id="AKIA...",
    aws_secret_access_key="...",
    scopes=["import", "export"],
    export_base_path="exports/review",
    import_mode="new_only",
)

client.connectors.test(connector.connector_id)

job = client.import_jobs.create(
    connector_id=connector.connector_id,
    index_id="idx_archive",
    source_prefix="incoming/2026/04/",
    file_pattern="*.mp4",
    recursive=True,
)

Export results and configure a webhook

export = client.exports.create_index_export(
    index_id="idx_archive",
    prompt_run_ids=[run.run_id],
    destination_connector_id=connector.connector_id,
    destination_subpath="exports/review",
)

webhook = client.webhooks.create(
    name="Prompt terminal events",
    url="https://example.com/webhooks/videovector",
    events=["prompt_run.completed", "prompt_run.failed", "export.ready"],
)

Playground workflows

Use playground media when the asset should remain outside a named index.

playground_upload = client.videos.upload(file="/tmp/sample.mp4", title="Playground sample")
playground_results = client.search.playground(query="crowd near station")