Video Operations

Extract thumbnails and frames from video files at specific timestamps.

Generate Video Thumbnail

POST /api/v1/jobs/video/thumbnail

Extract a thumbnail image from a video at a specific timestamp.

Request Body

{
  "source_bucket": "my-bucket",
  "source_key": "videos/movie.mp4",
  "dest_bucket": "my-bucket",
  "dest_key": "thumbnails/movie-thumb.jpg",
  "timestamp": "00:00:05",
  "width": 1280,
  "format": "jpeg"
}

Parameters

Parameter	Type	Required	Description
source_bucket	string	✅	Source S3 bucket
source_key	string	✅	Source S3 key (video file)
dest_bucket	string	✅	Destination S3 bucket
dest_key	string	✅	Destination S3 key (image file)
timestamp	string	❌	Time position (format: HH:MM:SS or seconds, default: 00:00:01)
width	integer	❌	Thumbnail width in pixels (maintains aspect ratio)
format	string	❌	Output format: jpeg, png, webp (default: jpeg)

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Job queued for processing"
}

Examples

Basic Thumbnail

curl -X POST http://localhost:8080/api/v1/jobs/video/thumbnail \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "source_bucket": "my-bucket",
    "source_key": "video.mp4",
    "dest_bucket": "my-bucket",
    "dest_key": "thumbnail.jpg"
  }'

Specific Timestamp

curl -X POST http://localhost:8080/api/v1/jobs/video/thumbnail \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "source_bucket": "my-bucket",
    "source_key": "video.mp4",
    "dest_bucket": "my-bucket",
    "dest_key": "thumbnail-5s.jpg",
    "timestamp": "00:00:05",
    "width": 1920,
    "format": "webp"
  }'

JavaScript

const response = await fetch('http://localhost:8080/api/v1/jobs/video/thumbnail', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    source_bucket: 'my-bucket',
    source_key: 'video.mp4',
    dest_bucket: 'my-bucket',
    dest_key: 'thumbnail.jpg',
    timestamp: '00:00:10',
    width: 1280
  })
});
const data = await response.json();

Timestamp Formats

You can specify timestamps in multiple formats:

HH:MM:SS

"timestamp": "00:01:30"

1 minute, 30 seconds

MM:SS

"timestamp": "01:30"

1 minute, 30 seconds

Seconds

"timestamp": "90"

90 seconds (1:30)

Use Cases

Video Previews

Generate preview thumbnails for video galleries and listings

Social Media

Create Open Graph images for video content sharing

Video Players

Generate sprite sheets for video scrubbing interfaces

Content Moderation

Extract frames for automated content analysis

Tips & Best Practices

Choosing Timestamps

• Avoid the first second (often black frames)
• For automatic thumbnails, use 5-10% into the video
• Test different timestamps to find the most representative frame

Performance

Thumbnail extraction is fast, typically completing in 1-3 seconds for most videos. Larger videos or higher resolutions may take longer.

Batch Processing

Generate multiple thumbnails at different timestamps using Batch Operations:

{
  "jobs": [
    {
      "type": "video_thumbnail",
      "source_bucket": "my-bucket",
      "source_key": "video.mp4",
      "dest_bucket": "my-bucket",
      "dest_key": "thumb-5s.jpg",
      "parameters": { "timestamp": "00:00:05" }
    },
    {
      "type": "video_thumbnail",
      "source_bucket": "my-bucket",
      "source_key": "video.mp4",
      "dest_bucket": "my-bucket",
      "dest_key": "thumb-30s.jpg",
      "parameters": { "timestamp": "00:00:30" }
    }
  ]
}

Error Handling

Common Errors

• 400 Bad Request: Invalid timestamp format or missing required fields
• 404 Not Found: Source video doesn’t exist in S3
• 500 Internal Error: Video codec not supported or timestamp exceeds video duration

Supported Video Formats

Mend supports all formats that FFmpeg can decode:

• MP4 (H.264, H.265)
• WebM (VP8, VP9)
• MOV (QuickTime)
• AVI
• MKV
• FLV
• And many more…

Next Steps

• Learn about Image Operations
• Explore Audio Operations
• Set up Webhooks for completion notifications