Watermark

Overview

Overlay a logo/watermark on a video.

Scales the watermark image relative to video width and positions it at the chosen corner, edge-center, or center. Supports opacity control.

Example: {"url": "https://cdn.example.com/video.mp4", "watermark_url": "https://cdn.example.com/logo.png", "position": "bottom_right"}

Options

Option	Type	Required	Default	Allowed Values
url	string	Yes	—	Any reachable video file URL
watermark_url	string	Yes	—	Any reachable image URL (PNG with transparency recommended)
position	string	No	top_right	top_left, top_right, top_center, bottom_left, bottom_right, bottom_center, center
margin	int	No	10	0–500 (pixels)
opacity	float	No	1.0	0.0–1.0
scale	float	No	0.15	0.01–1.0 (fraction of video width)

Endpoint

POST https://eranol.com/api/v1/ffmpeg/video/watermark

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "watermark_url": "https://cdn.example.com/logo.png",
  "position": "bottom_right",
  "margin": 10,
  "opacity": 0.8,
  "scale": 0.15
}

Fields

Field	Type	Default	Description
url	string	—	Remote video file URL. Required.
watermark_url	string	—	Watermark image URL. PNG with transparency recommended. Required.
position	string	top_right	Named position: top_left, top_right, top_center, bottom_left, bottom_right, bottom_center, center.
margin	int	10	Margin in pixels from the video edges. Range 0–500.
opacity	float	1.0	Watermark opacity. 1.0 = fully visible, 0.5 = semi-transparent, 0.0 = invisible.
scale	float	0.15	Watermark width as a fraction of video width (e.g. 0.15 = 15% of video width). Range 0.01–1.0.

Position Reference

Value	Placement
top_left	Top-left corner
top_right	Top-right corner
top_center	Horizontally centered, flush with the top edge
bottom_left	Bottom-left corner
bottom_right	Bottom-right corner
bottom_center	Horizontally centered, flush with the bottom edge
center	Centered in the frame

margin applies to all positions except center (which has no edge to offset from).

Response Example

{
  "job_id": "f595b9ad-1e15-4452-b7c2-8f8ff09c0a34",
  "status": "pending",
  "message": "Job created. Poll status_url for progress.",
  "job_type": "watermark",
  "result_url": "https://eranol.com/api/v1/ffmpeg/result/f595b9ad-1e15-4452-b7c2-8f8ff09c0a34",
  "status_url": "https://eranol.com/api/v1/ffmpeg/status/f595b9ad-1e15-4452-b7c2-8f8ff09c0a34"
}

Use Cases

1. Logo bottom-right, semi-transparent (default-style watermark)

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "watermark_url": "https://cdn.example.com/logo.png",
  "position": "bottom_right",
  "margin": 10,
  "opacity": 0.8,
  "scale": 0.15
}

2. Full-opacity brand mark, top-center

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "watermark_url": "https://cdn.example.com/logo.png",
  "position": "top_center",
  "margin": 20,
  "opacity": 1.0,
  "scale": 0.12
}

3. Small subtle mark, bottom-center

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "watermark_url": "https://cdn.example.com/logo.png",
  "position": "bottom_center",
  "margin": 15,
  "opacity": 0.5,
  "scale": 0.08
}

4. Centered watermark (e.g. preview/draft stamp)

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "watermark_url": "https://cdn.example.com/draft-stamp.png",
  "position": "center",
  "opacity": 0.3,
  "scale": 0.4
}

Error Codes

Code	Meaning
401	Missing or invalid API key
402	Insufficient credits
422	Validation error — check your request body
429	Rate limit exceeded — slow down requests
500	Internal server error — try again or contact support