Images and files

Prezly stores uploaded media with Uploadcare. The API returns file metadata, while the file itself is delivered from Prezly's media CDN. An uploaded image's UUID identifies the asset; it is separate from the story UUID.

Recognize the media representationCopy Anchor Link

An uploaded file uses this shape. The values below are illustrative:

{
  "version": 2,
  "uuid": "33333333-3333-4333-8333-333333333333",
  "filename": "press-kit.pdf",
  "mime_type": "application/pdf",
  "size": 14983
}

Images add their original dimensions and an ordered effects array:

{
  "version": 2,
  "uuid": "44444444-4444-4444-8444-444444444444",
  "filename": "collection.jpg",
  "mime_type": "image/jpeg",
  "size": 83736,
  "original_width": 1600,
  "original_height": 900,
  "effects": ["/crop/1200x800/center/"]
}

size is in bytes. version: 2 describes the file metadata format, not the story format. Preserve the metadata when using the file in a content node.

Media inside a structured document is already an object. Some separate story image fields are JSON-encoded strings or null; parse those fields according to their response schema before using their properties.

Build a delivery URLCopy Anchor Link

Use the UUID with Prezly's CDN origin:

https://cdn.uc.assets.prezly.com/YOUR_FILE_UUID/

For a download link, use /-/inline/no/ to request attachment delivery, optionally followed by an encoded filename. A browser's download attribute alone is not a reliable way to force a download from another origin.

<a href="https://cdn.uc.assets.prezly.com/YOUR_FILE_UUID/-/inline/no/press-kit.pdf">
  Download the press kit
</a>

Use the asset UUID returned by the API or upload service; the illustrative UUIDs above do not identify real files.

Preserve editorial image effectsCopy Anchor Link

An image's effects describe operations such as a crop chosen by its author. Append them in order using Uploadcare's /-/ operation separator, then add delivery transformations appropriate to your layout.

This standalone JavaScript example constructs an image URL without fetching the asset:

const image = {
  uuid: '44444444-4444-4444-8444-444444444444',
  effects: ['/crop/1200x800/center/'],
};
const operations = image.effects.map((effect) => effect.replace(/^\/+|\/+$/g, ''));
operations.push('preview/800x800', 'format/auto');
const src = `https://cdn.uc.assets.prezly.com/${image.uuid}/-/${operations.join('/-/')}/`;
console.log(src);

The resulting URL preserves the crop, fits the displayed image within 800 × 800 pixels, and requests an appropriate output format. These operations do not overwrite the original upload. See Uploadcare's URL API for supported transformations and their limits.

For responsive layouts, generate several bounded image widths and use srcset/sizes, or your framework's image component. Supply useful alt text, preserve captions, and avoid stretching small images beyond what the layout needs. Original dimensions describe the source upload; a crop can change the displayed aspect ratio.

For newsroom media collections with their own public pages, see Newsroom galleries.

The React renderer handles common media blocks. If you override its image or gallery components, preserve their file effects rather than rebuilding every URL from the UUID alone.

Upload a file before referencing itCopy Anchor Link

To prepare new media, upload the binary first, read its metadata, then include a Prezly file object in the story's content. Uploading alone does not create a story, attach the asset to a story, or grant permission to update one.

Prezly's upload endpoint is https://uploads.uc.assets.prezly.com/ and its public Uploadcare project key is 97775dfb0ac5a6446bce. This is a public upload key, not your Prezly bearer token. Do not send your API token to this service.

For a local file named press-image.jpg:

curl --fail-with-body --silent --show-error 'https://uploads.uc.assets.prezly.com/base/' \
  --form 'UPLOADCARE_PUB_KEY=97775dfb0ac5a6446bce' \
  --form 'UPLOADCARE_STORE=1' \
  --form 'file=@press-image.jpg'

The multipart field name determines the response key; here the uploaded UUID is returned under file. Copy it into the metadata request:

curl --fail-with-body --silent --show-error --get 'https://uploads.uc.assets.prezly.com/info/' \
  --data-urlencode 'pub_key=97775dfb0ac5a6446bce' \
  --data-urlencode 'file_id=YOUR_UPLOADED_FILE_UUID'

Wait for the upload to be ready. Use the metadata response to construct the Prezly representation: uuid, filename (the original filename), mime_type, size, and version: 2. For an image, also copy image_info.width/height to original_width/original_height and start with effects: [].

Keep the distinction between Uploadcare's response and Prezly's file object: uploading does not return an entire ready-to-save story node. Image nodes use type: "image-block" and a file object; attachments use type: "attachment". Preserve each node's other required properties when authoring content.

See the Uploadcare Upload API for the upload protocol. Reading or writing a Prezly story still uses the authentication and permissions for that endpoint.