Thumbnails

Take a poster frame, or frames at the times you choose, as JPEG or PNG images.

POST /v1/thumbnails writes images from a video: the most representative frame of the start, or frames at the times you choose.

A poster frame#

Without a time, the API picks the frame most like the rest of the first 300.

bash

curl "$VIDEXO_API_URL/v1/thumbnails" \
  -H "Authorization: Bearer $VIDEXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "https://example.com/talk.mp4",
  "filename": "poster.jpg",
  "resize": {
    "width": 640
  }
}'

JavaScript

const response = await fetch(`${process.env.VIDEXO_API_URL}/v1/thumbnails`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEXO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "input": "https://example.com/talk.mp4",
    "filename": "poster.jpg",
    "resize": {
      "width": 640
    }
  }),
});
const job = await response.json();

bash

ffmpeg \
  -i https://example.com/talk.mp4 \
  -map 0:v:0 \
  -vf thumbnail=300,scale=640:7680:force_original_aspect_ratio=decrease:force_divisible_by=2 \
  -frames:v 1 -q:v 2 \
  poster.jpg

poster.jpg: one JPEG, 640 pixels wide, the frame most like the rest of the first 300; "at": 10 takes the frame at 10 s instead.

Frames at chosen times#

times writes one file per time, named thumbnail_1.jpg, thumbnail_2.jpg and so on. Each time seeks into the input, so a frame late in a long video costs about what an early one costs.

bash

curl "$VIDEXO_API_URL/v1/thumbnails" \
  -H "Authorization: Bearer $VIDEXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "https://example.com/talk.mp4",
  "times": [
    5,
    30,
    60
  ],
  "resize": {
    "width": 320
  }
}'

JavaScript

const response = await fetch(`${process.env.VIDEXO_API_URL}/v1/thumbnails`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEXO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "input": "https://example.com/talk.mp4",
    "times": [
      5,
      30,
      60
    ],
    "resize": {
      "width": 320
    }
  }),
});
const job = await response.json();

bash

ffmpeg \
  -ss 5 -i https://example.com/talk.mp4 \
  -ss 30 -i https://example.com/talk.mp4 \
  -ss 60 -i https://example.com/talk.mp4 \
  -map 0:v:0 \
  -vf scale=320:7680:force_original_aspect_ratio=decrease:force_divisible_by=2 \
  -frames:v 1 -q:v 2 \
  thumbnail_1.jpg \
  -map 1:v:0 \
  -vf scale=320:7680:force_original_aspect_ratio=decrease:force_divisible_by=2 \
  -frames:v 1 -q:v 2 \
  thumbnail_2.jpg \
  -map 2:v:0 \
  -vf scale=320:7680:force_original_aspect_ratio=decrease:force_divisible_by=2 \
  -frames:v 1 -q:v 2 \
  thumbnail_3.jpg

The poster preset#

poster is a JPEG within 1280 by 720; at picks the time.

bash

curl "$VIDEXO_API_URL/v1/thumbnails" \
  -H "Authorization: Bearer $VIDEXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "https://example.com/talk.mp4",
  "preset": "poster",
  "at": 42
}'

JavaScript

const response = await fetch(`${process.env.VIDEXO_API_URL}/v1/thumbnails`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEXO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "input": "https://example.com/talk.mp4",
    "preset": "poster",
    "at": 42
  }),
});
const job = await response.json();

bash

ffmpeg \
  -ss 42 -i https://example.com/talk.mp4 \
  -map 0:v:0 \
  -vf "scale='min(iw,1280)':'min(ih,720)':force_original_aspect_ratio=decrease:force_divisible_by=2" \
  -frames:v 1 -q:v 2 \
  thumbnail.jpg

format: "png" writes PNG instead of JPEG. A time past the end of the input fails the job with processing_failed (reason time_past_end) before ffmpeg runs.