How artwork fits into your CMS.

The integration model

The Picker helps an editor choose artwork. Your CMS then saves the selection and decides how to display it. Vieunite supplies the current metadata, rights and image files.

If your CMS needs its own image files, you can import the selected version into your media library when rights allow. Keep the Collection reference beside the local media record so you can track its source and recheck availability. The Nexus case study shows that workflow.

Production and Test are isolated

Each environment has its own API, hosted Picker, SDK origin and tenant credentials. Use Test for integration work, then move all three URLs and the issued credential to Production as one deployment change.

Never send a Test token to Production or a Production token to Test. Register the exact CMS callback origins separately in each environment.

Resources

Artwork and collection are selectable. Artists and categories help organise discovery but are not themselves Picker selections.

What to save: an artwork reference

A reference records which artwork and image version the editor chose. Its ID stays useful when the title or image URL changes, although the artwork may later become unavailable. Here are the two supported shapes:

{
  "provider": "vieunite-art-collection",
  "type": "artwork",
  "id": "art_456",
  "rendition": "crop"
}

{
  "provider": "vieunite-art-collection",
  "type": "collection",
  "id": "col_123"
}

Artwork versions

rendition is the key of the chosen image version, taken from available_versions[].key. For example, an editor might choose the original composition or an uploaded crop of the same artwork. Use the returned key unchanged; its spelling is not a rule for generating new versions.

• Show the versions the API returns.Not every artwork has a crop, square, 1080p and original. Use each version’s name as its label.
• A resolution label does not fix the shape.A 1080p version may be portrait or landscape. Use its delivery.width and delivery.height when laying out the image.
• Keep the editor’s choice.Send the saved rendition when resolving the reference and requesting a signed URL. Collections have no rendition of their own.
• Ask for a new choice if that version disappears.Handle rendition_unavailable instead of silently switching to another composition.

The asset guide explains how crops, squares and automatic 1080p versions are prepared.

Preview responses expose only nested preview dimensions for safe thumbnails. Authenticated responses additionally expose nested source and delivery dimensions for every available version. ratio remains accepted for legacy read-only references and as geometric metadata, but new integrations persist rendition.

Availability, rights and safety

A record can exist while being unavailable to a specific tenant or context. Plan level, publication window, rights, audience and safety policy are evaluated when the API lists or resolves content.

Resolve returns status: "available" or status: "unavailable". For an unavailable item, read reason to decide whether to refresh it or ask the editor to choose another artwork. Validate again before publishing.

Preview experience versus full data

Public previews show a limited set of metadata and safe preview images. Some editorial text is masked, and source and delivery dimensions are omitted. They are useful for trying the catalogue before integration.

The hosted Picker starts with lightweight search results. When an editor opens a result, its active session can load the complete authenticated details and a watermarked detail image. Your CMS gets the final references through the SDK, then uses the server API for metadata and image delivery. Internal preview and Picker routes are not integration endpoints.

Batch operations can partially succeed

A 200 OK does not mean every requested item succeeded. For example, nine artworks may resolve while a tenth is unavailable. Keep the nine results and show the editor what needs attention.