Skip to main content

Adding Watermarks To Images with Imgwire

Watermarks in Imgwire are delivery-time transformations. The original image stays unchanged, while the CDN URL controls the overlay, size, position, opacity, and optional effects.

Use this pattern for previews, generated image galleries, creator attribution, review assets, and branded derivatives.

Upload a reusable watermark asset​

For the most predictable workflow, upload your watermark graphic to the same Imgwire environment as the images it will overlay.

import fs from 'node:fs';
import { ImgwireClient } from '@imgwire/node';

const imgwire = new ImgwireClient({
  apiKey: process.env.IMGWIRE_API_KEY!,
});

const watermark = await imgwire.images.upload({
  file: fs.createReadStream('assets/watermark.png'),
  fileName: 'watermark.png',
  mimeType: 'image/png',
  purpose: 'watermark asset',
  customMetadata: {
    role: 'watermark',
  },
});

console.log(watermark.id);

Store the watermark image ID in your app configuration or CMS settings.

Apply the watermark​

Retrieve the target image and generate a delivery URL with watermark, watermark_size, and watermark_position.

const image = await imgwire.images.retrieve('img_123');
const watermarkImageId = process.env.IMGWIRE_WATERMARK_IMAGE_ID!;

const watermarkedUrl = image.url({
  width: 1200,
  format: 'auto',
  quality: 'auto',
  watermark: watermarkImageId,
  watermark_size: '160',
  watermark_position: 'southeast:-32:-32:0.85',
});

In watermark_position, southeast anchors the watermark to the bottom-right corner. Negative offsets move it inward from the edge. The final value, 0.85, controls opacity.

The raw URL shape is:

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=1200&watermark={watermark_image_id}&watermark_size=160&watermark_position=southeast:-32:-32:0.85&format=auto&quality=auto

Use a text watermark​

Use watermark_text when you need a quick label and do not need a separate graphic:

const previewUrl = image.url({
  width: 1200,
  format: 'auto',
  quality: 'auto',
  watermark_text: 'Preview',
  watermark_position: 'southeast:-32:-32:0.75',
});

Text watermarks are useful for internal review assets, draft previews, or simple attribution labels.

Use a public URL watermark​

Use watermark_url when the watermark lives outside Imgwire at a public HTTPS URL:

const watermarkedUrl = image.url({
  width: 1200,
  watermark_url: 'https://example.com/brand-watermark.png',
  watermark_size: '160',
  watermark_position: 'southeast:-32:-32:0.85',
  format: 'auto',
});

The SDK base64-encodes raw HTTPS values for watermark_url before building the delivery URL. If you build URLs by hand, encode the URL yourself before placing it in the query string.

Add a shadow or rotation​

For watermarks that need more contrast, add a shadow:

const url = image.url({
  width: 1200,
  watermark: process.env.IMGWIRE_WATERMARK_IMAGE_ID!,
  watermark_size: '140',
  watermark_position: 'southeast:-32:-32:0.9',
  watermark_shadow: '020B10:8:4:6',
  format: 'auto',
  quality: 'auto',
});

For editorial or draft styles, rotate the watermark:

const url = image.url({
  width: 1200,
  watermark_text: 'Draft',
  watermark_position: 'center:0:0:0.5',
  watermark_rotate: '-18',
  format: 'auto',
});

Apply watermarks consistently​

Centralize your watermark settings so the same surface produces the same URL shape:

const WATERMARK_OPTIONS = {
  watermark: process.env.IMGWIRE_WATERMARK_IMAGE_ID!,
  watermark_size: '160',
  watermark_position: 'southeast:-32:-32:0.85',
} as const;

export function buildWatermarkedPreview(image: {
  url: (options: object) => string;
}) {
  return image.url({
    width: 1200,
    format: 'auto',
    quality: 'auto',
    ...WATERMARK_OPTIONS,
  });
}

Stable transformation options keep CDN variants reusable and make visual QA easier.

Best practices​

  • Upload reusable watermark graphics to Imgwire and reference them by image ID.
  • Use opacity and inset offsets so the watermark is visible without covering important content.
  • Set watermark_size instead of relying on the watermark asset's original dimensions.
  • Keep watermark assets in the same environment as target images.
  • Treat watermarks as visual indicators, not access control.

Last updated at: May 8, 2026