Images

An image output can be WebP or AVIF, a smaller JPEG or PNG, or cropped around what draws the eye. These run on libvips, with mozjpeg and oxipng. POST /v1/thumbnails takes them, as does an output of type image in POST /v1/jobs.

The request#

curl "$VIDEXO_API_URL/v1/thumbnails" \
  -H "Authorization: Bearer $VIDEXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "https://example.com/photo.jpg",
  "filename": "photo.webp",
  "resize": {
    "width": 640,
    "height": 640,
    "fit": "cover",
    "anchor": "attention"
  }
}'

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/photo.jpg",
    "filename": "photo.webp",
    "resize": {
      "width": 640,
      "height": 640,
      "fit": "cover",
      "anchor": "attention"
    }
  }),
});
const job = await response.json();

photo.webp: one WebP, 640 pixels square, cut around the part of the picture that draws the eye.

What these images hold#

• Turned as it should be. A JPEG with an EXIF orientation comes out turned.
• No metadata. EXIF, GPS, XMP and IPTC do not reach the file, whatever strip_metadata says.
• sRGB. Every one of these images is written in sRGB: a colour profile is applied and dropped, so a wide gamut photo loses the colours outside sRGB. This may change during the preview, and the changelog would say so.
• One picture. A file with several pages or frames is refused when it is read directly, and through ffmpeg the output takes one frame, as any image does.

An image output that asks for none of these runs on ffmpeg as it always has, with its ffmpeg_command. One that does shows null in the command fields, and steps lists ffmpeg, vips or oxipng.

What it reads#

When an input's URL ends in .jpg, .jpeg, .png or .webp, and the output asks for no size or for a box of width and height that it fits or covers around its centre or by attention, libvips reads the file itself. The name only chooses this route: its first bytes must say JPEG, PNG or WebP, whichever of them it is, or the job fails with processing_failed, reason media_unreadable, even if ffmpeg could read it. Such a file can have up to 100 megapixels and 65,500 pixels on a side; past that the job fails with limit_exceeded, reason image_pixels.

Everything else goes through ffmpeg first, with the size limits of any image output: an upload, a video, an AVIF, a GIF or a BMP, any output with at, times, crop, rotate, flip, color, sharpen, blur, overlays or text, and a resize with one side, aspect, fit: "pad" or an anchor on an edge. TIFF and HEIC are not read.

What it costs#

JPEG, PNG and WebP cost 1 credit an image, a PNG with optimize 2 and AVIF 3. Each image includes 3 s of processing, and a slow one pays for the time past that (Billing).