The Vionlabs Asset Ingestion and Processing Guide describes how to upload, register, and process your video assets using the Vionlabs API ecosystem.
It provides an end-to-end walkthrough of the content ingestion pipeline — from uploading video files to your cloud storage, through Catalog and Task API ingestion, to retrieving AI-generated results.

This guide is intended for engineers and integrators responsible for managing video catalogs and automated processing flows within the Vionlabs platform.

1. Overview

The ingestion and processing workflow is the foundation of the Vionlabs platform.
It defines how your content enters the system, is analyzed by AI models, and becomes enriched with metadata and insights such as mood, genre, ad break suggestions, or highlight scenes.

At a high level, the process involves four key steps:

• Upload your video files to cloud storage (Google Cloud Storage or AWS S3).
• Ingest your assets via the Catalog API — defining their metadata and file location.
• Trigger processing using the Task API or automatic processing for activated products.
• Retrieve results via the Results API once processing is complete.

2. Before You Start

Before ingesting content, ensure the following prerequisites are met:

Your video files are uploaded to a bucket in Google Cloud Storage or AWS S3.

You have a valid Vionlabs API key.

File paths use full URIs (e.g., gs://your-bucket/asset.mp4, not relative paths).

The asset files are accessible and readable from your configured credentials.

⚠️ Common mistake: Attempting to ingest an asset that hasn’t yet been uploaded to your bucket will result in an “asset not found” error.

3. Asset Types

Vionlabs supports two main types of video assets: Movies (Standalone) and Episodes.

3.1 Movies / Standalone Assets

These represent a single, independent video file — such as a film, documentary, or one-off special.

Required fields:

id: Unique identifier for the asset

type: Always standalone

title: Display name of the asset

asset_info.file_uri: Full cloud storage path to the video file

Example:

curl -X 'PUT' \ "https://apis.prod.vionlabs.com/catalog/v1/item?key=$YOUR_API_KEY" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d ‘{  "id": "MOVIE-001",  "type": "standalone",  "title": "Sample Movie Title",  "asset_info": {    "file_uri": "gs://your-bucket/sample-movie.mp4"  } }’

3.2 Episodic Assets

Episodes belong to a hierarchical content structure (Series → Season → Episode).
They require additional metadata to correctly organize the series structure and maintain relationships.

Required fields:

id, type, title

asset_info.file_uri

extended_episodic_info block containing:

series_id, series_title

season_id, season_title

season_number, episode_number

Example:

curl -X 'PUT' \ "https://apis.prod.vionlabs.com/catalog/v1/item?key=$YOUR_API_KEY" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{  "id": "EPISODE-001",  "type": "episode",  "title": "Pilot Episode S01E01",  "asset_info": {    "file_uri": "gs://your-bucket/series/season1/episode1.mp4"  },  "extended_episodic_info": {    "series_id": "SERIES-001",    "series_title": "Example Series",    "season_id": "SEASON-001",    "season_title": "Season 1",    "season_number": 1,    "episode_number": 1  } }'

4. Processing Workflows

After ingestion, assets can be processed automatically or selectively depending on your configuration.

4.1 Auto-Processing via Catalog API

When assets are ingested and products are active in your account, processing begins automatically.
This is the default method for most integrations — simple, fast, and efficient.

4.2 Controlled Processing via Task API

If you need more control (e.g., selecting which product or version to run), use the Task API.
It allows you to manually trigger, monitor, and cancel processing jobs for specific assets.
Learn more in the Task API Guide.

5. Retrieving Results

Once an asset has been successfully processed, all insights and metadata become available through the Results APIs.

Each product has its own dedicated endpoint and response schema.

Examples of available Result APIs:

All Result APIs use the same authentication key as the Catalog API and are accessible only for assets within your account’s configured permissions.

6. Maintaining Your Catalog

The Catalog API also enables maintenance operations for updating or managing your assets:

List assets: GET /catalog/v1/item

Upsert or update: PUT /catalog/v1/item

Delete items: PUT /catalog/v1/delete/{type}/{ident}

In addition, Vionlabs supports:

Poster ingestion for artwork (see Posters Ingestion Guide)

Force reprocessing to refresh analysis results without deleting assets
("operations": { "force_asset_reprocess": true })

⚠️ Force reprocessing is limited to once per 24 hours per asset to prevent overuse and maintain system performance.

7. Best Practices

To ensure smooth ingestion and accurate results, follow these best practices:

• 🗂️ Organize your cloud bucket structure — group related content logically (e.g., per customer or per catalog).
• 🔑 Use consistent naming conventions for all files and IDs.
• 🚫 Do not rename files after ingestion — this breaks the link between file URI and asset ID.
• 🧩 Maintain consistent series and season IDs across all episodes.
• 🧪 Test ingestion with a small batch before scaling to large catalogs.
• 📋 Keep a record of asset IDs for tracking and results retrieval.
• ✅ Verify each ingestion via API response before submitting additional assets.

8. Troubleshooting

If persistent issues occur, contact Vionlabs Support with your API key, asset ID, and request payload for analysis.

9. Summary

The ingestion and processing workflow is the backbone of how the Vionlabs platform transforms raw video into actionable insights.
By following this guide, you ensure that your assets are ingested correctly, processed efficiently, and maintained consistently across your catalog.

This approach enables you to build a scalable, automated, and high-quality pipeline for video analysis — empowering better editorial decisions, personalization, and content intelligence across your media products.

For additional technical details and API schema references, visit:
👉 https://docs.vionlabs.com/catalog_integration/