Platform model

VideoVector's public workflow model is intentionally composable. You define the media collection, define the extraction logic, run that logic against a target, then search or deliver the outputs.

The same model supports schema-aware metadata extraction, video-to-vector embeddings, multimodal media embeddings, and hybrid vector and metadata search. metadata_text connects structured prompt output to the semantic retrieval layer without removing the exact fields needed for filters and exports.

Core entities

Indexes

An index is the primary collection boundary for media and related workflows.

• Media can be uploaded directly into an index or imported into it from a connector.
• Search is usually anchored to an index, even when the request also spans multiple indexes.
• Import and export automations are configured per index.
• Webhooks can be scoped to all indexes or a selected set of index IDs.

Media

A media item is a video, audio file, or image stored in the platform.

• Media appears with a video_id even when the media type is audio or image.
• Media can be uploaded directly, created from a URI, or imported from a connector.
• A media item can participate in multiple prompt runs over time.
• Media exposes segment views, processing state snapshots, markers, preview helpers, and batch inspection utilities.

Prompts

A prompt defines what the platform extracts.

• prompt_text contains the segment-level instruction.
• json_schema defines the segment-level output contract.
• video_level optionally adds a separate video-wide or audio-wide synthesis stage.
• semantic_indexing lets you exclude selected output leaves from semantic embedding.

Prompt runs

A prompt run is one execution of one prompt against one target.

• The target can be an entire index, a selected list of media IDs, or playground media.
• Each run records execution settings such as segmentation mode, durations for fixed segmentation, model selection, transcription, and image embeddings.
• Runs expose status, per-media counts, failure manifests, segment retry state, and optional video-level result availability.

Results

A completed run produces two public result layers:

• Segment-level results: one result per processed segment with structured metadata and metadata_text.
• Video-level results: one synthesis result per media item when video_level is enabled on the prompt.

Search primarily works across segment-level results, while video-level outputs are retrieved directly from a run when needed.

How public workflows connect

1. Create an index.
2. Upload media or import it from a connector.
3. Create a prompt with a JSON schema.
4. Execute a prompt run against the index, a selected set of media items, or playground content.
5. Inspect run state and results.
6. Search, export, automate, or deliver the outputs.

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/indexes \
  -H "Authorization: Bearer <token-or-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Broadcast Archive"}'

Collections versus executions

Use the entity boundaries consistently:

• Use an index when you need a stable collection boundary.
• Use a prompt when you need a reusable extraction contract.
• Use a prompt run when you need execution-specific state, results, and auditability.

That separation is important for search as well. Search requests can limit to:

• all searchable runs in an index
• selected run IDs
• multiple indexes
• structured filters over prompt output fields

Delivery resources

Once outputs exist, the rest of the public surface is about movement and orchestration:

• Connectors define cloud storage access.
• Import jobs pull media into an index.
• Exports write prompt results out as downloadable or connector-delivered artifacts.
• Automations schedule import and export behavior per index.
• Webhooks push lifecycle events to your own endpoints.

What is intentionally not part of the public model

This documentation does not define internal queue mechanics, worker topology, scaling behavior, or credit and billing flows. Those are not required to use the platform successfully.