Overlay

Overview

Overlay text or an image on a video with per-frame rendering.

Supports:

• Text overlay using drawtext (with font, colour, position control)
• Image overlay using the overlay filter (PNG recommended)
• Image sizing relative to the video (fit) or by exact pixels (width / height)
• Time-range control (start_sec / end_sec)
• Opacity control
• Multiple overlays in a single request (overlays array)

Example (text): {"url": "https://cdn.example.com/video.mp4", "type": "text", "content": "LIVE", "position": "top_right", "font_color": "red"}

Example (image): {"url": "https://cdn.example.com/video.mp4", "type": "image", "content": "https://cdn.example.com/badge.png", "position": "bottom_left"}

Endpoint

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

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "type": "text",
  "margin": 15,
  "content": "LIVE",
  "end_sec": 10,
  "position": "top_right",
  "font_size": 32,
  "start_sec": 0,
  "font_color": "#ff0000"
}

Fields

Field	Type	Applies to	Description
url	string	both	Remote video file URL. Required.
type	string	both	"image" or "text". Required in single-overlay mode (ignored when overlays is set).
content	string	both	For image: the image URL. For text: the display string.
overlays	array	—	Array of overlay objects for multiple overlays in one request. When provided, the single-overlay fields are ignored.
position	string	both	Named position when x/y are not set: top_left, top_right, bottom_left, bottom_right, center.
margin	int	both	Margin from video edges (px) when using a named position. Range 0–500.
x	int	both	Horizontal position in pixels from the left edge. Overrides position.
y	int	both	Vertical position in pixels from the top edge. Overrides position.
start_sec	float	both	When to start showing the overlay (seconds). null = from the beginning.
end_sec	float	both	When to stop showing the overlay (seconds). null = until the end.
opacity	float	both	Overlay opacity. 1.0 = fully visible, 0.0 = invisible.
font_size	int	text	Font size. Range 8–200.
font_color	string	text	Named colour (white, red, …) or hex (#RGB / #RRGGBB).
fit	string	image	Size the image relative to the video frame. See Image Sizing.
width	int	image	Explicit overlay width in pixels. See Image Sizing.
height	int	image	Explicit overlay height in pixels. See Image Sizing.
scale	float	image	Scale multiplier of the image's own size. See Image Sizing.

Image Sizing

For image overlays, size is controlled by one of three fields. Precedence is fit > width/height > scale. If none are set, the image is used at its native pixel size.

Field	Type	Description
fit	string	Sizes the image relative to the video frame. Overrides width/height/scale. One of: fill, cover, contain, none (default).
width	int	Explicit overlay width in pixels. Overrides scale. If only width is set, height auto-scales to preserve aspect ratio.
height	int	Explicit overlay height in pixels. Overrides scale. If only height is set, width auto-scales to preserve aspect ratio.
scale	float	Multiplier of the image's own size (e.g. 0.15 = 15% of the source image). Note: the result depends on how large the source image is.

fit modes:

Value	Behaviour
fill	Stretch to exactly cover the whole video frame (full-screen). Ignores aspect ratio.
cover	Scale to cover the frame preserving aspect ratio, cropping any overflow.
contain	Scale to fit inside the frame preserving aspect ratio (may leave gaps).
none	Default. Use width / height / scale instead.

Tip — full-screen image: use "fit": "fill" (stretch) or "fit": "cover" (no distortion, crops edges). This works regardless of the source image's resolution, so you don't need to pre-resize it to match the video.

Response Example

{
  "job_id": "f595b9ad-1e15-4452-b7c2-8f8ff09c0a34",
  "status": "pending",
  "message": "Job created. Poll status_url for progress.",
  "job_type": "video_overlay",
  "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. Live badge text (top-right, timed)

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "type": "text",
  "margin": 15,
  "content": "LIVE",
  "end_sec": 10,
  "position": "top_right",
  "font_size": 32,
  "start_sec": 0,
  "font_color": "#ff0000"
}

2. Single image watermark (named position, semi-transparent)

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "type": "image",
  "scale": 0.1,
  "margin": 20,
  "content": "https://cdn.example.com/watermark.png",
  "opacity": 0.5,
  "position": "bottom_right"
}

3. Single image overlay (exact pixel position, timed)

Request Body

{
  "x": 50,
  "y": 50,
  "url": "https://cdn.example.com/video.mp4",
  "type": "image",
  "scale": 0.15,
  "content": "https://cdn.example.com/badge.png",
  "end_sec": 8,
  "opacity": 0.8,
  "start_sec": 2
}

4. Multiple overlays — image + text together

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "overlays": [
    {
      "x": 20,
      "y": 20,
      "type": "image",
      "scale": 0.12,
      "content": "https://cdn.example.com/logo.png",
      "opacity": 0.9
    },
    {
      "type": "text",
      "margin": 20,
      "content": "Breaking News",
      "end_sec": 12,
      "position": "bottom_left",
      "font_size": 40,
      "start_sec": 3,
      "font_color": "#ffffff"
    }
  ]
}

5. Multiple timed image overlays (e.g. sponsor logos swapping in/out)

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "overlays": [
    {
      "x": 30,
      "y": 30,
      "type": "image",
      "scale": 0.15,
      "content": "https://cdn.example.com/sponsor-a.png",
      "end_sec": 10,
      "opacity": 1,
      "start_sec": 0
    },
    {
      "x": 30,
      "y": 30,
      "type": "image",
      "scale": 0.15,
      "content": "https://cdn.example.com/sponsor-b.png",
      "end_sec": 20,
      "opacity": 1,
      "start_sec": 10
    }
  ]
}

6. Full-screen image sequence (timed cutaways)

Display a series of full-screen images at timed intervals. fit: "fill" stretches each image to cover the entire video frame regardless of its source resolution. Use fit: "cover" instead if you want to avoid any distortion (it preserves aspect ratio and crops the edges).

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "overlays": [
    {
      "type": "image",
      "content": "https://cdn.example.com/frame-1.jpg",
      "x": 0,
      "y": 0,
      "start_sec": 0,
      "end_sec": 3,
      "opacity": 1,
      "fit": "fill"
    },
    {
      "type": "image",
      "content": "https://cdn.example.com/frame-2.jpg",
      "x": 0,
      "y": 0,
      "start_sec": 4,
      "end_sec": 7,
      "opacity": 1,
      "fit": "fill"
    }
  ]
}

7. Image overlay with exact pixel dimensions

Size the overlay to a precise pixel box instead of a scale multiplier. Set only width (or only height) to preserve aspect ratio automatically.

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "type": "image",
  "content": "https://cdn.example.com/logo.png",
  "x": 40,
  "y": 40,
  "width": 200,
  "opacity": 0.9
}

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