Know exactly what you receive.

Three layers form one asset delivery

Available image content

Availability is per artwork. Do not assume that every work has every row below; read available_versions from the current response.

1080p and 4K do not imply 16:9. A version can be landscape, portrait or square. For example, 1080p delivery can be 1920 × 1080, 1080 × 1920, 1920 × 1920 or another ratio-preserving size. Vieunite does not synthesize a square crop, a 16:9 crop or any other requested canvas.

• No generated cropNo reframing, padding, stretching or ratio change.
• No rotation assumptionResolution class is independent of landscape or portrait orientation.
• No upscaleThe automatic 1080p version is created only from an eligible 4K source.

Current file format

The current Collection image pipeline normalises delivered artwork images and thumbnails to RGB progressive JPEG. The API remains MIME-described so integrations can evolve without changing stored rendition keys.

available_versions[] format

This array is the authoritative list of versions an editor can choose and a CMS can request. The authenticated catalogue and reference responses include source and delivery facts.

{
  "key": "auto_1080p",
  "name": "1080p",
  "source_kind": "derived",
  "resolution_class": "1080p",
  "ratio": "9:16",
  "orientation": "portrait",
  "preview": {
    "width": 540,
    "height": 960,
    "mime_type": "image/jpeg"
  },
  "source": {
    "width": 2160,
    "height": 3840
  },
  "delivery": {
    "width": 1080,
    "height": 1920,
    "mime_type": "image/jpeg"
  },
  "is_default": false
}

A derived 1080p item deliberately keeps the 4K parent dimensions under source while delivery describes the smaller file. Preview experiences omit both source and delivery so original resolution is never exposed there.

assets format

The assets map contains physical helper files for the artwork record. It is useful for a default catalogue card or schema.org output, but it is not the list of editor-selectable versions.

{
  "assets": {
    "thumbnail": {
      "id": "asset_art_456_thumbnail",
      "variant": "thumbnail",
      "url": "https://assets.example.com/public/artworks/art_456/thumbnail.jpg",
      "access": "public",
      "width": 540,
      "height": 960,
      "mime_type": "image/jpeg"
    }
  }
}

GET /v1/capabilities publishes the current helper asset vocabulary. That list is not a rendition catalogue. Always enumerate selectable content from available_versions.

Request the selected delivery

Call the signed URL endpoint from your CMS backend with assets:signed_url:create. Despite the legacy request field name variant, its value is the opaque available_versions[].key.

curl --request POST "https://collection.vieunite.com/v1/assets/signed-urls" \
  -H "Authorization: Bearer $VIEUNITE_TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "requests": [
    {
      "artwork_id": "art_456",
      "variants": [
        "crop",
        "auto_1080p",
        "original"
      ]
    }
  ],
  "expires_in": 900
}'

{
  "data": [
    {
      "asset_id": "asset_art_456_display__1080p",
      "artwork_id": "art_456",
      "variant": "display__1080p",
      "version_key": "auto_1080p",
      "url": "https://assets.example.com/...?Expires=...&Signature=...",
      "expires_at": "2026-07-16T16:45:00Z",
      "access": "signed_url"
    }
  ],
  "denied": [
    {
      "artwork_id": "art_456",
      "variant": "original",
      "reason": "restricted"
    }
  ]
}

• version_key is the join key.Match it to the stored rendition and available_versions[].key.
• variant is physical.It can be display for a requested crop, or display__1080p for auto_1080p. Do not persist it.
• Dimensions and MIME are not repeated.Read them from the matching available_versions[].delivery object and confirm the final HTTP headers.
• The signed URL is already authorized.Use GET without the tenant Bearer token. Treat the URL itself as a secret capability until it expires.

Handle partial delivery

A successful HTTP 200 can contain both issued grants and denied items. Process every element instead of treating the batch as all-or-nothing.

Where each form is provided

Recommended CMS flow

1. 1

   Persist the selectionSave provider, type, artwork ID and the exact Picker rendition.

2. 2

   Resolve current truthRequest rights, availability, assets, available_versions, version and updated_at.

3. 3

   Find the version descriptorMatch the stored rendition to available_versions[].key and read delivery.

4. 4

   Request a grantSend that same rendition key to POST /v1/assets/signed-urls.

5. 5

   Render with rightsUse the matching version_key, reserve the returned delivery dimensions, and honour license, allowed uses and credit-display requirements.

6. 6

   Refresh instead of persisting URLsRe-resolve after a resource change and request a new URL after expires_at.

• Do not persist signed URLs in CMS content fields.
• Do not log signed query strings or send them to analytics.
• Do not construct rendition keys from names, dimensions, ratios or orientations.
• Do not assume every artwork has 1080p, 4K, square and Original Ratio versions.
• Do reserve image layout from delivery.width and delivery.height to avoid layout shift.