Skip to main content
Almost every app that reads a creator’s account needs to show their media: Vault folders, chat attachments, post images. Two things trip people up, and both have a supported answer.
  1. The media URL you get back is short-lived, so a URL you stored yesterday may fail to load today.
  2. Some list endpoints return media without image URLs, which tempts you into slow, repeated lookups.
This guide shows the intended patterns for both.

​
How media and variants work

A media item has a stable uuid that never changes, and one or more variants. A variant is a specific rendition of the item at a specific size or treatment, each with its own URL.
VariantUse it for
thumbnailSmall previews in lists and grids
thumbnail_galleryLarger gallery previews
mainThe full-size image or video
blurredA locked or teaser state for unpurchased media
The important rule: you only get variant URLs when you ask for them. List endpoints return a minimal shape (uuid, status) by default. Pass the variants query parameter to get the full object back, including a variants array where each entry has a url, variantType, width, height, and displayPosition.
Always filter to ready media with status=ready. An item that is still processing does not have usable variant URLs yet.

​
Treat media URLs as short-lived

Variant URLs are signed and expire. They are designed to be fetched when you need them, not stored.
Do not persist signed media URLs in your database and render them later. By the time a user opens the page, a stored URL may have expired and will return 403 or 404 from the CDN.
Store the stable identifiers instead (mediaUuid, and for chat media the messageUuid), then resolve a fresh URL at display time. The pattern:
1

Store IDs, not URLs

Persist mediaUuid (and messageUuid for chat attachments). These never change.
2

Resolve on demand

When something scrolls into view, request the variants you need for those IDs.
3

Cache in memory, briefly

Hold the resolved URL in memory for the current view. Do not write it to durable storage.
4

Refetch on failure

If a render fails with 403 or 404, resolve the URL again rather than retrying the dead one.

​
Display Vault media efficiently

GET /vault/folders/{folderName}/media lists what is in a folder, but it returns lightweight items without variant URLs. Resolving each one by scanning the full media list is the slow path that causes hundreds of calls per folder view. The supported path is to list the folder’s media directly from the media endpoint with variants included. GET /media accepts a folderName filter, a variants list, and status: 
curl "https://api.fanvue.com/media?folderName=Campaign%20assets&variants=thumbnail,main&status=ready&page=1&size=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"
Each item in data comes back with its variants array, so you get thumbnail and full-size URLs in one paged response instead of one lookup per item. Page through with page and size to load a folder.
Pick the smallest variant that fits the surface. Render grids and lists with thumbnail, and only resolve main when the user opens an item full-screen.

​
Resolve specific media by ID

When you already hold a set of media UUIDs (for example, IDs you stored earlier), resolve them in a batch rather than one request each. GET /media/bulk takes a comma-separated mediaUuids list and a variants list: 
curl "https://api.fanvue.com/media/bulk?mediaUuids=UUID_A,UUID_B,UUID_C&variants=thumbnail,main" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"
This is the right tool for re-resolving fresh URLs for media you are about to show.

​
Display chat media reliably

Chat attachments follow the same short-lived-URL rule. Sync and store each message’s stable IDs (messageUuid, mediaUuid), then resolve fresh URLs only for the media a user is actually viewing. GET /chats/{userUuid}/messages/{messageUuid}/media resolves attachments for a single message. It takes mediaUuids (comma-separated, up to 20) and an optional variants list: 
curl "https://api.fanvue.com/chats/$USER_UUID/messages/$MESSAGE_UUID/media?mediaUuids=UUID_A,UUID_B&variants=thumbnail,main" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"
Call this lazily as media scrolls into view, in batches of up to 20 UUIDs, and cache each resolved URL in memory until you navigate away. If an image 403s, resolve it again.

​
Putting it together

  • Store IDs, never signed URLs.
  • Ask for the variants you need, and filter with status=ready.
  • Use folderName on GET /media to load a Vault folder with thumbnails in one call per page.
  • Use GET /media/bulk or the per-message media endpoint to re-resolve URLs on demand.
  • Treat 403 and 404 on a media URL as “resolve again”, not as a hard error.
Stay mindful of rate limits: resolving lazily, in batches, and only for visible media keeps you well clear of the per-user limit.