Image URLs and parameters

This page is the client-facing reference for fetching images. For the conceptual overview see Image service. For the editorial / admin side see Image management.

URL pattern

https://<tenant>.image-service.<region>.vmnd.tv/api/v2/img/<imagePackId>[?<query>]

Segment	Meaning
`<tenant>`	Customer tenant (e.g. `vimond`, `sales`) — same value used across other VIA services.
`<region>`	Environment, for example `eu-north-1-prod`, `eu-north-1-dev`.
`<imagePackId>`	Image pack identifier. Typically the Content Discovery payload supplies this verbatim. May include a `-` suffix that acts as a cache buster (see below).

Example (verbatim from Content Discovery):

https://sales.image-service.eu-north-1-prod.vmnd.tv/api/v2/img/62e89a0ce4b0003c6f22b5a3-1662654467834?location=portal-cover&width=300&height=450

Discovering image pack IDs

Image pack IDs are returned alongside assets and categories from the Content Discovery API. Use the supplied templates rather than constructing URLs yourself when possible:

"images": {
  "defaultUrl": "https://sales.image-service.eu-north-1-prod.vmnd.tv/api/v2/img/62e89a0ce4b0003c6f22b5a3-1662654467834",
  "templates": {
    "locations": ["portal-landscape-cover", "portal-cover", "portal-carousel", "thumb", "main"],
    "withLocation": "https://sales.image-service.eu-north-1-prod.vmnd.tv/api/v2/img/62e89a0ce4b0003c6f22b5a3-1662654467834?location=${LOCATION}",
    "withRegion":   "https://sales.image-service.eu-north-1-prod.vmnd.tv/api/v2/img/62e89a0ce4b0003c6f22b5a3-1662654467834?region=${REGION}",
    "complete":     "https://sales.image-service.eu-north-1-prod.vmnd.tv/api/v2/img/62e89a0ce4b0003c6f22b5a3-1662654467834?region=${REGION}&location=${LOCATION}"
  }
}

See the full discovery walk-through in Content Images.

Cache busting

Two equivalent options:

Append a timestamp to the imagePackId (preferred): …/api/v2/img/62e89a0ce4b0003c6f22b5a3-1662654467834. The handler treats anything after the last - as opaque — the pack still resolves to 62e89a0ce4b0003c6f22b5a3 — but the URL string is unique, so a deployment can invalidate stale variants by bumping the suffix.
Send a date query parameter: ?date=<timestamp>. Same effect; useful when the imagePackId is referenced elsewhere by its raw form.

Avoid arbitrary query parameters not listed below. The parameters-normalizer Lambda strips unknown keys before computing the cache key, so they neither bust the cache nor reach the image-processing step.

Query parameters

All parameters are optional. When omitted, the handler falls back to defaults (often configured per location on the management side).

Name	Type	Default	Description
`location`	string	`main`	Named location on the pack (e.g. `main`, `thumb`, `portal-cover`). Case-sensitive. If the location is unknown, the handler falls back to the first location on the pack and finally to `main`; if no images exist the response is `404 Not Found`.
`width`	integer (px)	original / location config	Requested pixel width. Use `*` together with a `height` to leave the dimension free and preserve aspect ratio (only one of width/height required).
`height`	integer (px)	original / location config	Requested pixel height.
`resize-mode`	enum	`crop`	`crop` fills the requested box, removing parts of the original that fall outside. `includeAll` zooms out and pads with transparency so the whole original is included — served as PNG to preserve the alpha channel.
`resize-gravity`	enum	`center`	Cardinal anchor for `resize-mode`: `north`, `northeast`, `east`, `southeast`, `south`, `southwest`, `west`, `northwest`, `center`. Controls which part of the image is kept when cropping or where padding is placed when including all.
`rounded-corners`	integer (px)	`0`	Corner radius applied to the output. Forces PNG/WebP/AVIF output to preserve transparency.
`skip-crop`	boolean	`false`	When `true`, ignores the pack’s stored `cropInfo` and uses the original image bounds. Useful for editorial previews.
`location-ratio`	boolean	`false`	When `true`, the aspect ratio defined in the location config is forced; supplied `width` / `height` are interpreted as targets within that ratio.
`format`	enum	source format, then `jpeg`	Output format. Accepted: `webp`, `jpeg` (alias `jpg`), `png`, `gif`, `avif`. Animated locations always serve `avif` regardless of this value.
`date`	string	—	Cache-buster passthrough. The value is included in the cache key but otherwise ignored.
`region`	string	—	Geographic publishing region; honored when the pack defines region-specific imagery. Most tenants don’t use region-keyed packs.

Examples

Default image for a pack:

https://vimond.image-service.eu-north-1-prod.vmnd.tv/api/v2/img/62e89a0ce4b0003c6f22b5a3-1662654467834

A 300×450 portal cover, cropped center:

…/api/v2/img/62e89a0ce4b0003c6f22b5a3-1662654467834?location=portal-cover&width=300&height=450

Include the whole image, padded with transparency, with 24 px rounded corners, as WebP:

…/api/v2/img/62e89a0ce4b0003c6f22b5a3-1662654467834?width=400&height=400&resize-mode=includeAll&rounded-corners=24&format=webp

Animated preview (location-controlled — format is ignored, response is AVIF):

…/api/v2/img/62e89a0ce4b0003c6f22b5a3-1662654467834?location=VIDEO_PREVIEW

Format negotiation

Static images default to the source format and fall back to jpeg if conversion is required.
Setting resize-mode=includeAll or rounded-corners > 0 forces a transparency-capable format (png, webp, or avif).
The VIDEO_PREVIEW and VERTICAL_VIDEO_PREVIEW locations always serve the original animated asset as avif, regardless of other parameters. No resizing or transformation is applied.

Access keys

Some tenants require a per-request access key. Provide it either as a header or a query parameter; the header wins if both are supplied.

curl --location 'https://<tenant>.image-service.<region>.vmnd.tv/api/v2/img/<imagePackId>' \
  --header 'X-vimond-access-key: <accessKeyValue>'

…/api/v2/img/<imagePackId>?X-vimond-access-key=<accessKeyValue>

Access keys are managed by the platform and synced into the CloudFront edge configuration automatically — you do not need to coordinate rotations with deployments.

Error responses

Status	Meaning
`200`	OK — image bytes returned in the negotiated format.
`301` / `302`	Variant exceeded the Lambda response size cap and is being redirected to its S3 location. Follow the redirect; the bytes are the same.
`404`	Image pack not found, or requested location is unknown and no fallback resolved to an image.
`403`	Missing or invalid `X-vimond-access-key` (when access keys are enforced for the tenant).
`422`	The original could not be decoded into a known image type (rare; reported back through to the management side at upload time).