Image location configs

An image location config is a tenant-wide definition of a named slot — main, thumb, portal-cover, etc. Every image pack inherits these defaults, and clients request a variant by passing ?location=<name> to the serving URL.

This page covers the admin endpoints for managing location configs. Client usage is covered in Image URLs and parameters.

Schema

A location config has the following fields. Only name and one of width / height are mandatory.

Field	Type	Description
`name`	string	Unique within the tenant. Used in the client URL as `?location=<name>`. Case-sensitive.
`label`	string	Human-friendly label used in the VIA CMS picker.
`width`	integer	Default pixel width. Leave unset to use the original width and only constrain `height`.
`height`	integer	Default pixel height. Leave unset to use the original height and only constrain `width`.
`fallback`	string	Name of another location to use if this one has no image on a given pack.
`resizeGravity`	enum	One of `north`, `northeast`, `east`, `southeast`, `south`, `southwest`, `west`, `northwest`, `center` (default). Controls anchoring when cropping.
`useResizeIncludeAll`	enum	`UNSET` (default), `TRUE`, `FALSE`. When `TRUE`, the serving layer always includes the whole original with transparent padding for this location, regardless of client `resize-mode`.
`added` / `updated`	string	Read-only timestamps set by the service.

At least one of width and height is required. Omitting one means “scale freely on that axis to preserve aspect ratio”.

List all location configs

curl --request GET \
  --url 'https://<tenant>.image-service.<region>.vmnd.tv/adminAPI/imageLocationConfigs' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <admin token>'

Returns an array of all configured locations for the tenant.

Create or update one location

curl --request PUT \
  --url 'https://<tenant>.image-service.<region>.vmnd.tv/adminAPI/imageLocationConfig/portal-cover' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <admin token>' \
  --data '{
    "label": "Portal Cover",
    "width": 600,
    "height": 900,
    "resizeGravity": "center",
    "useResizeIncludeAll": "UNSET"
  }'

The trailing path segment (portal-cover) is the location’s name. Sending an updated body to the same path replaces the config.

Bulk replace all location configs

curl --request PUT \
  --url 'https://<tenant>.image-service.<region>.vmnd.tv/adminAPI/imageLocationConfigs?force=true' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <admin token>' \
  --data '[
    { "name": "main",         "width": 1280, "height": 720 },
    { "name": "thumb",        "width": 160,  "height": 90  },
    { "name": "portal-cover", "width": 600,  "height": 900, "fallback": "main" }
  ]'

This replaces the entire list. Anything not present in the payload is removed.

About `force=true`

Any change to a location’s width, height, resizeGravity, or useResizeIncludeAll invalidates every previously generated variant for that location: the next request for any pack at that location will trigger a fresh resize through the image-processing Lambda. Because that can be a large amount of work in aggregate, the admin API requires the caller to acknowledge it explicitly with ?force=true.

Cosmetic changes (e.g. updating label only) do not require force=true.

Adding vs renaming

You can safely add a new location at any time — it has no variants to invalidate, so the first request for each pack just creates the resized variant on demand.

Renaming is not supported as a single operation. The migration looks like:

Create the new location with the desired name and config.
Update consumers (Content Discovery templates, players that hard-code location names) to use the new name.
Delete the old location once nothing references it.

If you simply want to make all packs share a different default size for an existing location, just update the size (force=true) — clients keep using the same ?location=<name> URL.

Verifying changes

After updating a location config:

curl --request GET \
  --url 'https://<tenant>.image-service.<region>.vmnd.tv/adminAPI/imageLocationConfigs' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <admin token>' \
| jq '.[] | select(.name=="portal-cover")'

The returned updated timestamp confirms the write. To verify the serving side picked up the change, request a known pack at that location with an arbitrary cache buster:

https://<tenant>.image-service.<region>.vmnd.tv/api/v2/img/<imagePackId>?location=portal-cover&date=<now>

The response is served fresh by image-processing if the variant was invalidated, then cached for subsequent requests. For broader invalidation patterns, see Image cache invalidation.