Thumbnail

Generate a smaller preview image from an image, video, or document.

File-first

width and height are both optional. Give one and the other is derived from the source's aspect ratio; give neither and the longest edge becomes 320px — either way the image is never distorted. The fit option (max / crop / scale) controls how the source is fitted to the requested dimensions. A null dimension is rejected with a GislConfigError before any upload — omit the key instead.

TypeScript

const result = await client
  .file('./photo.jpg')
  .thumbnail({ width: 200, height: 200 })
  .run({ maxWait: '5m' });

console.log(result.url);

PHP

$run = $client->file('./photo.jpg')
    ->thumbnail(['width' => 200, 'height' => 200])
    ->run(maxWait: '5m');

echo $run->url;

Python

Not available: the Python SDK is not published and no release is scheduled — see Python.

Rust

Not an application SDK: Rust is internal contract types — see Rust.

Options by media type

Option	Values	Default	Applies to
width / height	1–16384	Both omitted: longest edge 320px. One omitted: derived from the source aspect ratio.	All. Width × height ≤ 16 MP. Video rounds each down to an even number.
fit	max · crop · scale	crop	All.
format	jpg · png · webp	jpg	All. Note jpg, not jpeg.
quality	1–100	85 (jpg, webp); 70 (png)	Image input: jpg, webp and png. Video and documents: jpg and webp only.
background	#RRGGBB	—	Image input with format: 'jpg'.
timestamp	a string: seconds ('5') or HH:MM:SS	'00:00:01'	Video — the frame to extract.
source	page · cover	page	PDF, Office and OpenDocument. cover has no effect for these.
page	≥ 1	1	PDF, Office and OpenDocument, with source: 'page'.

• Image input: JPEG, PNG, GIF, WebP, TIFF, BMP, AVIF and HEIC.
• Video input: MP4, WebM and MOV. Input over 5 minutes (the long-form tier) is planned for thumbnail.
• EPUB takes source: 'cover' only — its default — and extracts the embedded cover image; source: 'page' is rejected.

TypeScript

// A frame five seconds in.
const frame = await client
  .file('./clip.mp4')
  .thumbnail({ width: 640, height: 360, timestamp: '5', format: 'webp' })
  .run({ maxWait: '5m' });

// Page 2 of a PDF.
const page = await client
  .file('./report.pdf')
  .thumbnail({ width: 400, height: 520, page: 2, format: 'png' })
  .run({ maxWait: '5m' });

PHP

// A frame five seconds in.
$frame = $client->file('./clip.mp4')
    ->thumbnail(['width' => 640, 'height' => 360, 'timestamp' => '5', 'format' => 'webp'])
    ->run(maxWait: '5m');

// Page 2 of a PDF.
$page = $client->file('./report.pdf')
    ->thumbnail(['width' => 400, 'height' => 520, 'page' => 2, 'format' => 'png'])
    ->run(maxWait: '5m');

Python

Not available: the Python SDK is not published and no release is scheduled — see Python.

Rust

Not an application SDK: Rust is internal contract types — see Rust.

Chaining

Thumbnail the output of a prior step in the same workflow — for example, compress first, then thumbnail the compressed result:

TypeScript

import { OptimizeFor } from '@giveitsmaller/sdk';

const result = await client
  .file('./photo.jpg')
  .compress(OptimizeFor.Size)
  .thumbnail({ width: 200, height: 200 })
  .run({ maxWait: '5m' });

PHP

use Gisl\Sdk\Generated\SdkSpec\Enums\OptimizeFor;

$run = $client->file('./photo.jpg')
    ->compress(OptimizeFor::Size)
    ->thumbnail(['width' => 200, 'height' => 200])
    ->run(maxWait: '5m');

Python

Not available: the Python SDK is not published and no release is scheduled — see Python.

Rust

Not an application SDK: Rust is internal contract types — see Rust.

See also

• Compress — reduce file size.
• Errors — handling failures.