The Posters Ingestion Guide explains how to add, manage, and update visual artwork for your video assets using the Vionlabs Catalog API.
Posters play a vital role in giving your catalog a polished and recognizable look inside the Vionlabs portal.
They help enhance discoverability, improve user experience, and ensure a visually consistent presentation across your content library.
1. Overview
Every asset in your catalog — whether a movie, documentary, or TV series — can be enriched with a custom poster.
Posters can be added via the Catalog API, either by linking to your own hosted images or by referencing external poster sources such as IMDb or TMDb.
Using your own image URLs gives you full control over artwork, while using third-party IDs allows for automatic poster updates when available.
2. Methods for Adding Posters
There are two supported ingestion methods for adding posters to your assets:
2.1 Using Your Own Posters
Use the poster_urls field in the Catalog API to reference your own artwork.
Benefits:
- ✅ Full control over image selection and branding
- ✅ Ability to localize and customize per customer or market
- ✅ No dependency on external databases
⚠️ Posters will not be auto-updated — you manage changes manually
2.2 Using External IDs (IMDb / TMDb)
Use the external_ids field to reference external poster sources.
Benefits:
- ⚙️ Automatic updates when the external database changes
- 🌍 Consistent, high-quality imagery
- 🚀 Easy to maintain for large catalogs
- ⚠️ Less control over artwork selection or localization
3. Poster Requirements
When ingesting posters using either method, make sure your images meet the following quality and format requirements:
| Parameter | Requirement |
|---|---|
| Aspect Ratio (width/height) | 2:3 |
| Resolution | 72 dpi |
| Minimum Size | 600 × 900 px |
| Language | English or the customer’s local language |
| Accessibility | Direct HTTPS URL (publicly accessible) |
Poster URLs must be direct links to the image files — not HTML pages, redirect links, or API endpoints.
Ensure your hosting supports public access for these assets.
4. Example API Call
Below is an example of how to set a poster URL using the Catalog API:
If you prefer to use external IDs:
For full API schema and examples, see the Catalog API documentation:
👉 https://apis.prod.vionlabs.com/catalog/docs#/default/upsert_item_catalog_v1_item_put
5. Best Practices
To ensure a smooth poster ingestion experience and consistent presentation:
🧩 Use consistent naming conventions across your assets and files.
🌐 Host your images reliably on HTTPS with stable URLs.
🎨 Maintain visual quality — blurry or off-ratio images may appear distorted in the portal.
🗂️ Store posters at the correct hierarchy level:
- For movies or standalone episodes, set the poster at the item level.
- For episodic content:
- By default, attach posters at the series level — they will be auto-propagated to all seasons.
- You can also attach posters at the season level if you want to customize per season.
- 🔁 Avoid frequent overwrites — if you need to refresh imagery, update only the poster field without altering the asset ID or file URI.
6. Required Fields for API Ingestion
When using the PUT method for adding or updating posters, the following fields are mandatory:
| Asset Type | Required Fields |
|---|---|
| Movies / Standalone |
id, type, title, asset_info.file_uri, plus poster_urls or external_ids
|
| Episodes |
Series level: id, type, title, asset_info.file_uri, plus poster_urls or external_idsSeason level: id, type, title, episodic_info (series_id, season_number), asset_info.file_uri, plus poster_urls or external_ids
|
Make sure to apply these fields in the correct structure to avoid ingestion errors.
7. Troubleshooting Tips
If a poster does not appear in your portal:
- Verify that the
poster_urlslink is public and reachable via HTTPS. - Check the image dimensions (must meet minimum requirements).
- Confirm that the poster was attached at the correct hierarchy (series level by default, or season level for customization).
- Validate your API response — ensure no validation or access errors are returned.
- If using external IDs, confirm the asset actually exists on IMDb or TMDb.
8. Summary
The Posters Ingestion process allows you to bring your catalog to life with consistent, high-quality artwork.
Whether you use your own hosted images or external data sources, following the API conventions and format requirements ensures your portal always displays professional-grade visuals.
By keeping your poster assets well-organized and up to date, you create a more intuitive and visually appealing experience for both your internal users and external partners.