Ittybit

Overview

The Thumbnails Task captures still image frames from a video file at regular intervals or specific moments.

Each thumbnail is generated as a separate Track file with "kind": "thumbnails" and stored as an image (.jpg or .png).

Thumbnails are used for media previews, cover images, or frame-by-frame analysis in video applications.

Example Output

{
  "id": "file_thmb12345",
  "object": "track",
  "kind": "thumbnails",
  "format": "jpg",
  "count": 3,
  "width": 640,
  "height": 360,
  "urls": [
    "https://live.ittybit.net/thumbnails/frame-1.jpg",
    "https://live.ittybit.net/thumbnails/frame-2.jpg",
    "https://live.ittybit.net/thumbnails/frame-3.jpg"
  ],
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}

Creating a Thumbnails Task

Thumbnails can be generated directly from a video URL or included within an automation workflow.

import { IttybitClient } from "@ittybit/sdk";

const ittybit = new IttybitClient({
  apiKey: process.env.ITTYBIT_API_KEY!
});

const task = await ittybit.tasks.create({
  kind: "thumbnails",
  url: "https://example.com/video.mp4",
  count: 3,
  width: 640,
  height: 360,
  description: "Generate 3 preview thumbnails",
  webhook_url: "https://your-app.com/thumbnails-webhook"
});

console.log("Task created:", task.id);
console.log("Status:", task.status);

When complete, the task produces one or more still image files which can be retrieved via API or webhook.

Webhook Example

app.post("/thumbnails-webhook", async (req, res) => {
  const { kind, status, results } = req.body || {};

  if (kind !== "thumbnails" || status !== "completed") {
    return res.status(200).send("Not a completed Thumbnails task");
  }

  console.log("Thumbnail URLs:", results.urls);
  console.log("Count:", results.count);

  res.status(200).send("Thumbnails generated");
});

File Structure

Property	Type	Description
id	string	Unique file ID for the thumbnails track.
object	string	Always "track".
kind	string	Always "thumbnails".
format	string	Image output format — "jpg" or "png".
count	number	Number of thumbnails generated.
width	number	Output width of each thumbnail.
height	number	Output height of each thumbnail.
urls	array	Public URLs for all generated thumbnails.
created / updated	string (ISO 8601)	Timestamps for creation and update.

Supported Inputs

Thumbnails can be generated from:

Video files: .mp4, .mov, .webm
Animated media: .gif, .avi

Example Workflow Integration

Thumbnails tasks are typically part of an Automation pipeline

alongside subtitles and chapters for end-to-end video processing.

{
  "name": "Video Processing Pipeline",
  "trigger": {
    "kind": "event",
    "event": "media.created"
  },
  "workflow": [
    { "kind": "video", "format": "mp4", "quality": 75 },
    { "kind": "subtitles", "ref": "video-subtitles" },
    { "kind": "thumbnails", "count": 3, "ref": "video-thumbnails" },
    { "kind": "chapters", "ref": "video-chapters" }
  ],
  "status": "active"
}

Each time a new media object is created, this workflow automatically generates compressed video outputs,

subtitle tracks, thumbnails, and chapter markers.

Example Use in Media Objects

When a video is processed, thumbnail files appear as part of the related Media Object:

{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  "files": [
    {
      "id": "file_thmb12345",
      "object": "track",
      "kind": "thumbnails",
      "type": "image/jpeg",
      "width": 640,
      "height": 360,
      "url": "https://live.ittybit.net/thumbnails/frame-1.jpg",
      "ref": "video-thumbnails"
    }
  ]
}

Example Display in HTML

Use thumbnails to display preview images or video selectors in your web app.

<div class="video-thumbnails">
  <img src="https://live.ittybit.net/thumbnails/frame-1.jpg" width="160" />
  <img src="https://live.ittybit.net/thumbnails/frame-2.jpg" width="160" />
  <img src="https://live.ittybit.net/thumbnails/frame-3.jpg" width="160" />
</div>

Common Use Cases

Generating video previews and posters
Selecting keyframes for editing interfaces
Improving UX for media galleries
Creating multi-frame summaries or reels

Summary

The Thumbnails task generates still image frames from a video file at defined intervals.

Each frame is output as a standalone image file for display, navigation, or preview generation,

and can be triggered directly or as part of an automation workflow.

Thumbnails

On this page