Image management

This section covers the management (admin) side of the Vimond Image Service — the API that ingest pipelines and CMS tooling use to upload originals, configure image locations, and crop images. End-user image fetching is covered separately in Image service and the URL & parameter reference.

When to read this

You are likely on this page if you are:

Integrating an ingest pipeline that uploads new images into Vimond.
Building admin/editor tooling that lets users adjust crop or add per-location variants.
Investigating why a published image isn’t showing or isn’t updating after an edit.

If you only need to fetch existing images from a player or website, skip to Image URLs and parameters.

Architecture in one slide

            ┌──────────────────────────────────────────────────┐
            │     Ingest / CMS  (this section)                  │
            │                                                   │
            │  PUT /adminAPI/imageLocationConfig/<name>         │
            │  POST /adminAPI/imagePacks                        │
            │  POST /adminAPI/imagePack/<id>/<loc>/upload       │
            │  PUT  /adminAPI/imagePack/<id>/<loc>  (cropInfo)  │
            │                                                   │
            │            Vimond Image Service (admin)           │
            └─────────────────────┬─────────────────────────────┘
                                  │ writes
                                  ▼
                      ┌─────────────────────────┐
                      │ S3: originals + metadata │
                      │ DynamoDB: image packs    │
                      └───────────┬─────────────┘
                                  │ DynamoDB stream
                                  ▼
                      ┌─────────────────────────┐
                      │ Invalidation aggregator  │
                      │ (every 5 minutes)        │
                      └───────────┬─────────────┘
                                  │ deletes & invalidates
                                  ▼
            ┌──────────────────────────────────────────────────┐
            │   Image handler  (client serving)                 │
            │   CloudFront → S3 variants → image-processing λ  │
            └──────────────────────────────────────────────────┘

Two key implications:

Updates propagate automatically. When you upload a new original or change cropInfo, the DynamoDB change stream queues an invalidation. Within ~5 minutes the affected CloudFront paths and S3 variants are dropped. Players see the new image on their next request.
imageLocationConfig changes are heavy. Changing the pixel size or resize behavior of a location forces every previously generated variant to be regenerated on demand. The admin API requires you to opt in with ?force=true so accidental edits don’t trigger a global rebuild. See Image location configs.

Core concepts

Concept	Description	Managed via
Image location config	Tenant-wide named slot — `main`, `thumb`, `splash`, `portal-cover`, … — with default width/height and resize behavior.	`/adminAPI/imageLocationConfig/<name>` and `/adminAPI/imageLocationConfigs`
Image pack	Collection of originals tied together by an `imagePackId`. Referenced from assets and categories. May carry per-pack resize overrides and per-location crop info.	`/adminAPI/imagePacks` and `/adminAPI/imagePack/<id>`
Image upload	Binary upload of an original for a (pack, location) combination. Originals are stored in S3 and resized on demand at serve time.	`/adminAPI/imagePack/<id>/<location>/upload`, `/adminAPI/imagePack/<id>/<location>/fetchImage`
Crop info	Per-location overrides on a pack: a normalized rectangle (`topLeftX`, `topLeftY`, `bottomRightX`, `bottomRightY` in `0.0`–`1.0`).	`PUT /adminAPI/imagePack/<id>/<location>`
Resize-include-all	Override that fills extra space with transparency instead of cropping when ratios mismatch. Resolved per request in this order: pack/location → pack → location config → tenant default.	Multiple endpoints accept `useResizeIncludeAll: UNSET \| TRUE \| FALSE`.

Auth

The admin API is mounted on the same hostname as the client API (https://<tenant>.image-service.<region>.vmnd.tv) but under /adminAPI/.

Authentication: Bearer JWT (scheme VimondAuth) for the platform-managed deployments behind the unified API. Legacy stand-alone deployments use HTTP Basic auth from application.conf.
Connection requirement: Requests must arrive over HTTPS or from a configured trusted IP.

Bearer tokens are obtained the same way as for other VIA admin APIs — see API authentication.

Typical flows

Adding a brand-new image location

Decide a name (lowercase, kebab-case is convention), pixel size, and resize policy.
PUT /adminAPI/imageLocationConfig/<name> with the JSON payload (see Image location configs).
If the location replaces or affects an existing one, communicate the rebuild cost — first hit on any pack for the new location will run image-processing.

Onboarding a new asset’s imagery

Create the image pack: POST /adminAPI/imagePacks (optionally with assetId to bind it).
Upload (or fetchImage by URL) one or more originals: POST /adminAPI/imagePack/<id>/<location>/upload.
If editors need a custom crop on a specific location: PUT /adminAPI/imagePack/<id>/<location> with cropInfo.
Store the returned id on the asset (imagePackId) via the REST API so Content Discovery can hand it to clients.

Replacing an existing image

Re-upload to the same (pack, location) — overwrites the original.
The DynamoDB stream emits a change event; the invalidation aggregator drops the affected variants from the CloudFront + S3 caches within ~5 minutes.
If you can’t wait, see Image cache invalidation for a manual DELETE you can fire from operator tooling.

Sub-guides

Image location configs — defining tenant-wide named locations.
Image packs — creating packs, uploading originals, cropping, fetch-by-URL.
Image cache invalidation — how the system invalidates automatically and how to invalidate manually.