#Watermark

Transcodely can burn a logo or image overlay directly into the encoded video of an output. A watermark is a per-output setting: it is baked into the frames of every rendition the output produces, so it cannot be turned off by the viewer — much like subtitle burn-in.

The watermark is configured through the watermark object on an Output Specification. The overlay image is fetched and validated at job creation, before any encoding starts.

#The WatermarkConfig object

A watermark is placed either relatively (the default, using anchor + width_pct + margin_pct) or by absolute pixels (pixel) — the two modes are mutually exclusive.

#Basic placement

In basic (relative) placement, the overlay is anchored to a named region of the frame and sized as a percentage of the output width. Because both the size (width_pct) and the margin (margin_pct) are expressed as percentages of each rendition’s own width, a single config places the overlay consistently across every ABR rung — the logo occupies the same relative area and sits the same relative distance from the edge on a 360p rung as it does on a 1080p rung. This is the recommended mode for multi-variant, HLS, and DASH outputs.

{
  "image_url": "https://cdn.example.com/logo.png",
  "anchor": "bottom_right",
  "width_pct": 12,
  "margin_pct": 3,
  "opacity": 0.85
}

All four relative fields have sensible defaults, so the minimum config is just an image_url — that yields a fully-opaque logo sized to 15% of the output width, inset 2% from the bottom-right corner.

#Raw pixel placement (hacker mode)

For advanced use, the pixel object places the overlay at an exact pixel offset and scales it to an exact pixel width. Unlike the relative fields, these coordinates do not adapt across ABR rungs — a placement tuned for a 1080p rung sits at the same pixel offset on a 360p rung, where it may be clipped or oversized. Pixel placement is therefore intended for single-rendition outputs, or for advanced users who accept that trade-off.

Supplying pixel together with any of anchor, width_pct, or margin_pct is rejected at job creation with a parameter_incompatible error on outputs[i].watermark.pixel. When using pixel mode, send only image_url, opacity (optional), and pixel.

#The WatermarkPixelPlacement object

{
  "image_url": "https://cdn.example.com/logo.png",
  "opacity": 0.9,
  "pixel": {
    "x": 48,
    "y": 48,
    "width": 240
  }
}

#Validation rules

The overlay image is fetched and validated at job creation, before any database write or encoding. Each distinct image_url across the job’s outputs is fetched at most once. The following constraints are enforced:

A fetch or format failure surfaces as a feature-validation error on outputs[i].watermark.image_url (parameter_invalid) with a user-safe message that never leaks internal fetch detail (the resolved IP, the SSRF target, or the underlying dial error).

#Pricing

A watermark is a pixel-burning overlay and requires a video re-render, so it is billed under the unified overlay multiplier: 1.1x, once per output. This is the same class as subtitle burn-in — a watermark and burned-in subtitles on the same output compose to a single 1.1x, never 1.21x. See Pricing — feature multipliers.

#Examples

The watermark object is set on an entry of the outputs array in a create-job request. All field names are snake_case and enum values are lowercase on the wire (e.g. "anchor": "bottom_right").

#Basic anchored watermark on an HLS output

A logo in the bottom-right corner, sized to 12% of each rendition’s width, at 85% opacity — scaled consistently across the whole ABR ladder.

{
  "type": "hls",
  "video": [
    {"codec": "h264", "resolution": "1080p", "quality": "standard"},
    {"codec": "h264", "resolution": "720p", "quality": "standard"},
    {"codec": "h264", "resolution": "480p", "quality": "standard"}
  ],
  "watermark": {
    "image_url": "https://cdn.example.com/logo.png",
    "anchor": "bottom_right",
    "width_pct": 12,
    "margin_pct": 3,
    "opacity": 0.85
  }
}

#Centered semi-transparent watermark on an MP4

{
  "type": "mp4",
  "video": [
    {"codec": "h264", "resolution": "1080p", "quality": "standard"}
  ],
  "watermark": {
    "image_url": "https://cdn.example.com/watermark.webp",
    "anchor": "middle_center",
    "width_pct": 30,
    "opacity": 0.4
  }
}

#Raw pixel placement on a single-rendition output

{
  "type": "mp4",
  "video": [
    {"codec": "h264", "resolution": "1080p", "quality": "standard"}
  ],
  "watermark": {
    "image_url": "https://cdn.example.com/logo.png",
    "opacity": 0.9,
    "pixel": {
      "x": 48,
      "y": 48,
      "width": 240
    }
  }
}