Workflow examples

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