Video Thumbnail Extractor - Multi-Platform Support

Extract high-quality thumbnails from videos across multiple platforms including YouTube, Vimeo, direct video URLs, and more.

🌟 Features

Multi-Platform Video Support

• YouTube - Extract thumbnails from any YouTube video
• Vimeo - Process Vimeo videos
• Dailymotion - Support for Dailymotion videos
• Direct Video URLs - MP4, AVI, MOV, MKV, WebM, FLV, WMV, M4V files
• Generic URLs - Automatic detection and processing via yt-dlp

Thumbnail Extraction Features

• ✅ Multiple Extraction Methods - Evenly spaced, custom timestamps, key frames, or beginning/middle/end
• ✅ Customizable Count - Extract 1-20 thumbnails per video
• ✅ High Quality - Configurable resolution and image quality
• ✅ Multiple Formats - Output as JPEG, PNG, or WebP
• ✅ Batch Processing - Process multiple videos simultaneously
• ✅ Automatic Upload - Store thumbnails in Apify Key-Value Store
• ✅ Base64 Encoding - Optional base64 encoded output
• ✅ Video Metadata - Extract title, duration, and other info

💰 Pricing - Pay Per Thumbnail

This actor uses tiered pay-per-event pricing based on extraction complexity:

Platform Type	Price per Thumbnail	Best For
YouTube (Native)	$0.001 (0.1¢)	YouTube videos - instant extraction
Direct URLs	$0.005 (0.5¢)	MP4, AVI, MOV files - frame streaming
Streaming Platforms	$0.01 (1¢)	Vimeo, Dailymotion - requires download

Why Tiered Pricing?

• YouTube Native: Uses YouTube's built-in thumbnails - minimal resources, minimal cost ⚡
• Direct URLs: Streams video frames directly - moderate resources, fair pricing 🎬
• Streaming Platforms: Requires full video download - maximum resources, premium pricing 📺

Example Costs

• 100 YouTube thumbnails: $0.10
• 100 Direct URL thumbnails: $0.50
• 100 Vimeo thumbnails: $1.00

See ./PRICING.md for detailed pricing information and examples.

📋 Input Parameters

Required

• videoUrls - Array of video URLs to process

Optional

• thumbnailCount - Number of thumbnails per video (default: 3, range: 1-20)
• extractionMethod - How to select frames:
  • evenly-spaced - Distribute thumbnails evenly across video (default)
  • custom-timestamps - Extract at specific timestamps
  • key-frames - Extract at key frames
  • beginning-middle-end - Extract from start, middle, and end
• customTimestamps - Array of timestamps in seconds (for custom-timestamps method)
• thumbnailWidth - Width in pixels (default: 1280, range: 320-3840)
• outputFormat - Image format: jpg, png, or webp (default: jpg)
• imageQuality - Quality 1-100 (default: 85)
• uploadToKeyValueStore - Store images in Key-Value Store (default: true)
• returnBase64 - Include base64 encoded images in output (default: false)

📝 Example Usage

Basic Example

{
  "videoUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "thumbnailCount": 3,
  "extractionMethod": "evenly-spaced",
  "outputFormat": "jpg"
}

Advanced Example - Custom Timestamps

{
  "videoUrls": [
    "https://www.youtube.com/watch?v=example",
    "https://vimeo.com/123456789",
    "https://example.com/video.mp4"
  ],
  "thumbnailCount": 5,
  "extractionMethod": "custom-timestamps",
  "customTimestamps": [10, 30, 60, 120, 180],
  "thumbnailWidth": 1920,
  "outputFormat": "png",
  "imageQuality": 95,
  "uploadToKeyValueStore": true,
  "returnBase64": false
}

High Quality Thumbnails

{
  "videoUrls": ["https://www.youtube.com/watch?v=example"],
  "thumbnailCount": 10,
  "extractionMethod": "evenly-spaced",
  "thumbnailWidth": 3840,
  "outputFormat": "png",
  "imageQuality": 100
}

📤 Output Format

Dataset Output

{
  "videoUrl": "https://www.youtube.com/watch?v=example",
  "platform": "youtube",
  "success": true,
  "processedAt": "2025-11-17T16:00:00.000Z",
  "thumbnailCount": 3,
  "thumbnails": [
    {
      "index": 0,
      "timestamp": 45.5,
      "timestampFormatted": "0:45",
      "keyValueStoreKey": "video_thumb_0.jpg"
    }
  ],
  "videoInfo": {
    "title": "Example Video",
    "duration": 180,
    "uploader": "Channel Name"
  }
}

Key-Value Store

Thumbnails are automatically uploaded to the Key-Value Store with keys like:

• video_thumb_0.jpg
• video_thumb_1.jpg
• etc.

Access them via:

https://api.apify.com/v2/key-value-stores/[STORE_ID]/records/[KEY]

🎯 Use Cases

Content Creation

• Generate video previews for websites
• Create thumbnail galleries
• Extract key moments from videos

Video Analysis

• Sample frames for quality checking
• Extract frames for machine learning training
• Create video summaries

Marketing

• Generate social media preview images
• Create video thumbnails for email campaigns
• Extract product shots from demo videos

🔧 Technical Details

Supported Video Platforms

• YouTube (all formats)
• Vimeo
• Dailymotion
• Direct video file URLs
• Any platform supported by yt-dlp (800+ sites)

Supported Video Formats

• MP4, AVI, MOV, MKV, WebM, FLV, WMV, M4V
• And many more via ffmpeg

Image Processing

• Powered by ffmpeg for frame extraction
• Sharp for image optimization and format conversion
• Maintains aspect ratio automatically
• High-quality output with configurable settings

⚙️ Configuration Tips

For Best Quality

{
  "thumbnailWidth": 1920,
  "outputFormat": "png",
  "imageQuality": 95
}

For Smaller File Sizes

{
  "thumbnailWidth": 1280,
  "outputFormat": "webp",
  "imageQuality": 75
}

For Specific Moments

{
  "extractionMethod": "custom-timestamps",
  "customTimestamps": [5, 30, 60, 120]
}

🚀 Performance

• Processes videos efficiently using ffmpeg
• Automatic cleanup of temporary files
• Optimized for batch processing
• Handles large videos (up to 500MB)

📊 Pricing

This actor uses standard Apify platform pricing based on:

• Compute units consumed
• Storage for Key-Value Store items

Typical usage:

• ~0.01 compute units per thumbnail extracted
• Storage costs for uploaded thumbnails

🔍 Troubleshooting

Video Download Fails

• Ensure the URL is publicly accessible
• Check if the platform is supported by yt-dlp
• Verify the video is not geo-restricted

Poor Quality Thumbnails

• Increase thumbnailWidth parameter
• Use PNG format for better quality
• Increase imageQuality setting

Timeout Issues

• Reduce thumbnailCount for long videos
• Use lower resolution settings
• Process videos in smaller batches

📚 Related Actors

• PDF OCR API - Extract text from PDF documents
• Image Processing API - Advanced image manipulation
• Video Metadata Extractor - Get detailed video information

📄 License

Apache-2.0

🤝 Support

For issues, questions, or feature requests, please contact HappiTap team.

---

Built with ❤️ using Apify, ffmpeg, yt-dlp, and Sharp