Image packs

An image pack is the unit that holds one or more original images plus per-location overrides. Assets, categories, and other VIA entities reference image packs by imagePackId; the serving layer then composes the right variant on demand. This page covers the admin endpoints for creating and maintaining packs.

For tenant-wide location defaults that every pack inherits, see Image location configs. For the client-facing URL that pulls a variant out of a pack, see Image URLs and parameters.

Schema

Field	Type	Description
id	string (read-only)	Service-assigned pack identifier, e.g. 62e89a0ce4b0003c6f22b5a3. Used in the client URL.
assetId	number	Optional. VIA Asset ID this pack belongs to — enables the imagePackViaAsset lookup.
mainImageLocation	string	Name of the location that holds the canonical original for the pack. Falls back to main if unset.
imageLocations	object	Map of location name → per-location overrides (cropInfo, useResizeIncludeAll, …).
useResizeIncludeAll	enum	Pack-level override: UNSET (default), TRUE, FALSE. Resolved after pack/location, but before the tenant imageLocationConfig default.
resizeGravity	enum	Pack-level gravity override applied when cropping (north, northeast, …, center).
tenant, created, modified, sequenceNumber	various (read-only)	Provenance set by the service.

Resize policy resolution

When the server needs to resize the original to fit a request, it picks useResizeIncludeAll from the first non-UNSET source in this order:

1. Per-location override on the image pack (imageLocations.<loc>.useResizeIncludeAll).
2. Pack-level (pack.useResizeIncludeAll).
3. Tenant imageLocationConfig for that location.
4. Tenant application default.

The same lookup logic applies to resizeGravity.

Crop info

Each per-location entry can carry cropInfo:

{
  "cropInfo": {
    "topLeftX": 0.10,
    "topLeftY": 0.05,
    "bottomRightX": 0.90,
    "bottomRightY": 0.95
  }
}

Coordinates are relative (0.0–1.0) so they survive original-image replacements. The rectangle is applied before any resize step. A client request can opt out with skip-crop=true (e.g. for editorial previews).

Lifecycle

Create a pack

curl --request POST \
  --url 'https://<tenant>.image-service.<region>.vmnd.tv/adminAPI/imagePacks' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <admin token>' \
  --data '{ "assetId": 554 }'

Returns the created pack including the new id. Store that value as the asset’s imagePackId via the REST API so Content Discovery can surface it to clients (see Content publishing for the asset-side write).

Look up by pack ID

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

Look up by asset ID

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

Update pack metadata

curl --request PUT \
  --url 'https://<tenant>.image-service.<region>.vmnd.tv/adminAPI/imagePack/62e89a0ce4b0003c6f22b5a3' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <admin token>' \
  --data '{
    "assetId": 4321,
    "useResizeIncludeAll": "UNSET"
  }'

List packs (paginated)

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

Returns at most 1000 IDs. Increment offset to paginate.

Uploading originals

You have two ways to give the service the actual image bytes.

Direct binary upload

curl --request POST \
  --url 'https://<tenant>.image-service.<region>.vmnd.tv/adminAPI/imagePack/62e89a0ce4b0003c6f22b5a3/main/upload' \
  --header 'Authorization: Bearer <admin token>' \
  --form 'file=@/path/to/original.jpg'

The path segment /main/ is the location name — the upload is associated with that location on the pack.

Fetch by URL (server-side download)

curl --request POST \
  --url 'https://<tenant>.image-service.<region>.vmnd.tv/adminAPI/imagePack/62e89a0ce4b0003c6f22b5a3/main/fetchImage?imageUrl=https://static.example.com/poster.jpg' \
  --header 'Authorization: Bearer <admin token>'

Useful for ingest pipelines where the source is already at a reachable URL. The service downloads and stores the original itself.

Either call returns 422 Unprocessable Entity if the bytes cannot be decoded as a known image format.

Per-location originals vs the main image

You do not need to upload an image for every location. If a client requests ?location=thumb and the pack has no thumb-specific original, the service uses the main image (or the location’s configured fallback) and resizes it to the thumb dimensions.

Upload location-specific originals only when you need editorial control (different framing, higher-resolution art, etc.) for that location.

Setting crop info

curl --request PUT \
  --url 'https://<tenant>.image-service.<region>.vmnd.tv/adminAPI/imagePack/62e89a0ce4b0003c6f22b5a3/portal-cover' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <admin token>' \
  --data '{
    "cropInfo": {
      "topLeftX": 0.0,
      "topLeftY": 0.10,
      "bottomRightX": 1.0,
      "bottomRightY": 0.90
    }
  }'

Sending {} as the body clears the per-location overrides for that (pack, location) — the location falls back to the pack/tenant defaults.

Downloading the stored original

For tooling that needs the raw bytes (e.g. editor preview):

curl --request GET \
  --url 'https://<tenant>.image-service.<region>.vmnd.tv/adminAPI/image/4fe1ad4ada06ed4bda5f43e2' \
  --header 'Authorization: Bearer <admin token>' \
  --output original.bin

The path component is the image file ID (different from the pack ID — packs contain one or more image file IDs). Tooling typically gets this by walking the pack’s imageLocations.

Binding a pack to an asset / category

The pack itself stores an optional assetId, but assets also need an imagePackId set on their side so Content Discovery can surface the URL templates. Set this through the Vimond REST API (PUT /api/web/asset/<id> or the equivalent category update):

{
  "imagePackId": "62e89a0ce4b0003c6f22b5a3-1647447599440"
}

The trailing -<timestamp> is the cache-busting suffix — bumping it whenever the pack changes is a robust way to force CDN re-fetch without relying solely on the automatic invalidation pipeline.

See also

• Image management overview
• Image location configs
• Image cache invalidation
• Image URLs and parameters — how clients consume what you publish here.
• Vimond Image Service API reference — full OpenAPI for these admin endpoints.