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) Time-range control (start_sec / end_sec) Opacity control Example (text): {"url": "https://cdn.example.com/video.mp4", "text": "LIVE", "position": "top_right", "font_color": "red"}

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

Example Request Bodies

Live badge text (top-right, timed)

{
  "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"
}

Single image watermark (named position, semi-transparent)

{
  "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"
}

Single image overlay (exact pixel position, timed)

{
  "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
}

Multiple overlays — image + text together

{
  "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"
    }
  ]
}

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

{
  "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
    }
  ]
}

Example Response

{
  "job_id": "f595b9ad-1e15-4452-b7c2-8f8ff09c0a34",
  "status": "pending",
  "message": "Job created. Poll status_url for progress.",
  "job_type": "caption",
  "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"
}