Watermarking

Add text, image, or combined watermarks to images and video — every parameter, with defaults and validation.

Fotovid watermarks both images and video with the same request shape and the same parameters. They differ only in the endpoint and the media limits.

	Endpoint	Task type	Output
Image	`POST /v1/image/watermark`	`image.watermark`	Watermarked image
Video	`POST /v1/video/watermark`	`video.watermark`	Watermarked MP4 (+ cover image)

Synchronous calls take { source_url, params } (the type comes from the URL). The async form adds a top-level type.

Two different type keys, don't mix them up: the top-level type is the task type (image.watermark / video.watermark), while params.watermark_type is the watermark variant (text / image / combo).

Watermark variants

text — render text over the media. Requires text.
image — overlay a logo from watermark_image_url. Requires watermark_image_url.
combo — logo and text together. Requires both.

Parameters

All parameters go inside params.

Parameter	Type	Default	Applies to	Notes
`watermark_type`	string	`text`	all	`text` \| `image` \| `combo`.
`text`	string	—	text, combo	Required for text & combo. Max 1000 chars.
`watermark_image_url`	string (URL)	—	image, combo	Required for image & combo. `image/*`, ≤ 32 MiB.
`position`	string	`bottom-right`	all	`top-left` \| `top-right` \| `bottom-left` \| `bottom-right` \| `center`.
`opacity`	number	`1`	all	`>0`–`1`.
`font_size`	int	`24`	text, combo	`8`–`200` (px).
`font_color`	string	`white`	text, combo	Letters-only name, or `#RRGGBB` / `#RRGGBBAA` (alpha).
`scale`	number	`0.15`	image, combo	Logo width = source width × scale. `>0`–`1`.
`padding`	int	`16`	all	Inset from the edge, `0`–`500` (px).
`preset`	string	x264 default	video	libx264 speed/size preset (`ultrafast`…`veryslow`).
`output_format`	string	`webp`	image output	`webp` \| `jpeg` \| `png`.
`quality`	int	`80`	image output	`1`–`100`. Ignored for `png`.

On video, output_format and quality affect only the generated cover image — the video itself is always MP4. Use preset to trade encode speed against file size for the video.

Output format

webp (default) — lossy, keeps transparency.
jpeg — lossy, flattens transparency to black.
png — lossless, keeps transparency; quality is ignored.

Examples

Text watermark (image, minimal — only text is required):

{
  "source_url": "https://cdn.example.com/photo.jpg",
  "params": {
    "watermark_type": "text",
    "text": "Fotovid.co",
    "position": "bottom-right",
    "font_size": 28,
    "font_color": "white",
    "opacity": 0.9
  }
}

Logo watermark (image):

{
  "source_url": "https://cdn.example.com/photo.jpg",
  "params": {
    "watermark_type": "image",
    "watermark_image_url": "https://cdn.example.com/logo.png",
    "scale": 0.15,
    "position": "top-right",
    "opacity": 0.8,
    "output_format": "png"
  }
}

Combo (logo + text) on video, submitted as an async task:

{
  "type": "video.watermark",
  "source_url": "https://cdn.example.com/clip.mp4",
  "params": {
    "watermark_type": "combo",
    "watermark_image_url": "https://cdn.example.com/logo.png",
    "text": "Fotovid.co",
    "position": "bottom-right",
    "preset": "veryfast"
  }
}

Validation

Bad parameters return 400 with a message naming the field — e.g. opacity is out of range, invalid position: <value>, or text is required for watermark type text. See Errors for the response shape.

Video watermarking is gated by both resolution and duration. The synchronous endpoint handles video up to 720p and 15 seconds; anything larger or longer returns a 409 — submit it as an async task (up to 4K). Sources above 4K are not supported on either path.