Introduction

The Task API Guide provides a practical introduction to managing processing workflows within the Vionlabs platform.
It describes how the Task API enables you to control which products process specific assets, monitor task execution, and handle selective or large-scale catalog operations efficiently.

Through this API, you can:

• Trigger processing for defined combinations of asset + product + version
• Check task progress and completion status in real time (pending, processing, done)
• Cancel processing jobs when necessary
• Troubleshoot common failure scenarios such as missing S3 assets, probe decoding errors, or unsupported video lengths

This guide is essential for teams integrating automated or event-driven processing pipelines. It helps you coordinate ingestion workflows with the Catalog API (a prerequisite for Task API usage) and provides a clear reference for building reliable, cost-efficient, and auditable processing operations at scale.

The Guide
 

1. Overview

The Task API enables you to decide which products should process specific assets and to monitor their processing status throughout the workflow.
It is particularly useful for platforms or customers managing large video libraries, where selective, incremental, or prioritized processing offers significant cost and performance benefits.

Key Benefits

• Selective processing: Run analysis only for selected assets instead of full catalog processing.
• Control over priorities: Assign different levels of processing priority (e.g., high, medium, low).
• Real-time monitoring: Retrieve up-to-date task status information for any running or completed job.
• Optimized cost-efficiency: Reduce unnecessary computation for assets that don’t need reprocessing.
   

2. Prerequisites

Before you can use the Task API, each asset must first be ingested via the Catalog API.
This step assigns the asset an internal Inventory ID, which is required when triggering tasks.

⚠️ Important: You cannot use the Task API directly without first registering the asset through the Catalog API ingestion endpoint.

3. Core Operations

The Task API exposes three main operations corresponding to task creation, monitoring, and cancellation.

3.1 Create a Processing Task

Endpoint:
POST /task

Use this endpoint to trigger a processing job for a specific combination of:

asset

product

version

Example use cases:

• Launch a re-analysis of an existing asset after a model update.
• Process new content selectively for only one AI product (e.g., Mood, Genre, AdBreak Detection).
   

3.2 Monitor Task Status

Endpoint:
GET /task/{task_id}

Retrieve the current status of any task. Possible states include:

pending – the task has been created and queued for processing

processing – the job is currently running

done – processing is complete

You can use this endpoint to integrate progress tracking into your internal dashboards or automation pipelines.

3.3 Cancel a Processing Task

Endpoint:
DELETE /task/{task_id}

Cancel a running or queued task for a specific combination of asset, product, and version.
This is useful if the processing job is no longer needed, the asset has changed, or a newer version of the product is being applied.

4. Common Error Scenarios

The Task API provides clear error messages when tasks fail or assets cannot be processed.
Below are the most frequent failure causes and their resolutions:

4.1 Asset Not Found in S3

Message: Asset not found in the provided S3 location.
This means the provided asset_url is invalid or the file doesn’t exist in your S3 bucket.
Resolution: Check your S3 path, verify permissions, and re-upload the asset to the correct location.

4.2 Probe Failed

Message: Probe failed with error = {ERROR}
This indicates that the system could not decode the asset — usually due to a corrupted or incompatible video file.
Resolution: Re-encode or re-upload the asset using a supported format.

4.3 Asset Too Short

Message: Asset shorter than the minimum required length.
For certain models, only assets longer than 10 minutes are supported.
Resolution: This asset cannot be processed. Short clips or trailers should be excluded from task creation.

4.4 Other Errors

If you encounter other, undocumented errors or irregular task statuses, contact Vionlabs Support with your task_id and asset_id for further investigation.

5. Best Practices

To ensure stable and efficient operation when using the Task API:

Batch Tasks Intelligently: Group assets by processing priority or product type to minimize queuing.

Monitor via Polling: Implement scheduled GET /task/{task_id} checks with reasonable intervals (e.g., every 30–60 seconds).

Handle Failures Gracefully: Log task responses and retry failed tasks only after resolving the root cause.

Combine with Catalog API: Use the Catalog API for ingestion and metadata registration, then trigger processing selectively via the Task API.

Track Results: Store task outcomes and timestamps to maintain a full processing history for auditing.

6. Summary

The Task API is the control center of the Vionlabs processing ecosystem.
It gives you fine-grained control over what gets analyzed, when it runs, and how to track its completion.
When integrated with the Catalog API and Result API, it forms a complete workflow for managing video asset analysis at scale — enabling selective processing, operational efficiency, and transparent monitoring across all your AI-powered products.

For more technical details and schema documentation, visit:
👉 https://docs.vionlabs.com/product_configuration/#task-api