Thumbnail

Overview

Generate a thumbnail from a video frame with text overlay.

Extracts the frame at the given timestamp and uses drawtext to render text with a background box.

Endpoint

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

Request Body

{
  "url": "https://cdn.example.com/video.mp4",
  "text": "Episode 1",
  "bg_color": "black@0.5",
  "position": "center",
  "font_size": 48,
  "timestamp": 5,
  "font_color": "white"
}

Response Example

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

Use Cases

1. Thumbnail with episode title overlay

Extract a frame at a specific timestamp and overlay the episode title as a large text label.

Request Body

{
  "url": "https://cdn.example.com/episode-5.mp4",
  "text": "Episode 5: Growth Strategies",
  "bg_color": "black@0.5",
  "font_size": 48,
  "timestamp": 30,
  "text_color": "white"
}

Response

{
  "job_id": "1406c589-a1f4-45d5-8745-aae07bc4de38",
  "status": "pending",
  "message": "Job created. Poll status_url for progress.",
  "result_url": "https://eranol.com/api/v1/ffmpeg/result/1406c589-a1f4-45d5-8745-aae07bc4de38",
  "status_url": "https://eranol.com/api/v1/ffmpeg/status/1406c589-a1f4-45d5-8745-aae07bc4de38"
}

2. Clean thumbnail without text

Extract a clean frame at a specific time without any text overlay — useful when text will be added client-side.

Request Body

{
  "url": "https://cdn.example.com/webinar-recording.mp4",
  "timestamp": 120
}

Response

{
  "job_id": "1406c589-a1f4-45d5-8745-aae07bc4de38",
  "status": "pending",
  "message": "Job created. Poll status_url for progress.",
  "result_url": "https://eranol.com/api/v1/ffmpeg/result/1406c589-a1f4-45d5-8745-aae07bc4de38",
  "status_url": "https://eranol.com/api/v1/ffmpeg/status/1406c589-a1f4-45d5-8745-aae07bc4de38"
}

3. Branded thumbnail with logo text

Overlay a company name in a custom colour at a specific position on the extracted frame.

Request Body

{
  "url": "https://cdn.example.com/tutorial.mp4",
  "text": "Eranol AI",
  "position": "bottom-right",
  "font_size": 36,
  "timestamp": 10,
  "text_color": "orange"
}

Response

{
  "job_id": "1406c589-a1f4-45d5-8745-aae07bc4de38",
  "status": "pending",
  "message": "Job created. Poll status_url for progress.",
  "result_url": "https://eranol.com/api/v1/ffmpeg/result/1406c589-a1f4-45d5-8745-aae07bc4de38",
  "status_url": "https://eranol.com/api/v1/ffmpeg/status/1406c589-a1f4-45d5-8745-aae07bc4de38"
}

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