DocsAPI referenceOperations

Grab thumbnails

One image at at (or the most representative of the first frames), or one file per time in times. Creates the same Job as POST /v1/jobs, with operation set.

POST /v1/thumbnails

Needs an API key: Authorization: Bearer $VIDEXO_API_KEY.

Parameters

Parameters
Name	In	Type	Description
`idempotency-key`	header	string, up to 255 characters	Makes retries safe for 24 hours. Up to 255 printable ASCII characters. One key space per account across every endpoint that creates a job.

Body ThumbnailsRequest

Body fields
Name	Type	Description
`input` required	string or object	An http or https URL, `videxo://uploads/<upload_id>`, `{ "url" }` or `{ "upload_id" }`.
`extra_inputs`	map of string to string or object
`webhook_url`	string, URL, up to 2,048 characters or null	An https URL that gets the job when it ends (M4).
`metadata`	map of string to string, up to 500 characters	Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500.
`filename`	string, up to 105 characters	The stored file name, `<name>.<format>` by default; one extension, matching `format`.
`format`	one of `mp4`, `mov`, `webm`, `mkv`, `ts`, `mp3`, `m4a`, `aac`, `wav`, `flac`, `ogg`, `opus`, `jpg`, `png`, `gif`, `json`	The container or image format; from `filename`, or the type's default.
`crop`	object	A rectangle of the input frame, in input pixels.
`rotate`	number	Degrees clockwise.
`flip`	one of `horizontal`, `vertical`	Mirror the picture.
`resize`	object	A new size: `width`, `height`, `aspect`, and how the picture fits (`fit`).
`color`	object	Brightness, contrast, saturation, gamma and hue.
`sharpen`	object	An unsharp mask.
`blur`	object	A box blur of the whole frame, or of up to 4 regions.
`overlays`	array of object	Images or videos drawn over the picture, in order.
`text`	array of TextLayer	Up to 8 text layers, drawn after overlays in order.
`at`	number, 0 to 86400 or string or string	The frame time, or `"auto"` for the most representative of the first 300 frames.
`times`	array of number, 0 to 86400 or string	One image per time, `<name>_1`, `<name>_2`, ...; not with `at`.
`quality`	one of `low`, `medium`, `high`	JPEG quality; PNG ignores it.
`strip_metadata`	boolean	Drop the input's global and stream metadata (GPS, device tags).
`preset`	one of `poster`	An image preset (`GET /v1/presets`); its options are the defaults and the output's own fields win.

Request

bash

curl "$VIDEXO_API_URL/v1/thumbnails" \
  -H "Authorization: Bearer $VIDEXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "https://videxo.io/samples/talk.mp4",
  "times": [
    2,
    7,
    12
  ],
  "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://videxo.io/samples/talk.mp4",
    "times": [
      2,
      7,
      12
    ],
    "resize": {
      "width": 640
    }
  }),
});
const job = await response.json();

Response

202 JSON

{
  "id": "job_3k9x0c2mfq8w1n7r5t4b6v2z",
  "state": "queued",
  "kind": "operations",
  "operation": "thumbnails",
  "spec": {
    "inputs": {
      "source": {
        "url": "https://videxo.io/samples/talk.mp4"
      }
    },
    "outputs": [
      {
        "name": "thumbnail",
        "type": "image",
        "input": "source",
        "filename": "thumbnail.jpg",
        "format": "jpg",
        "resize": {
          "width": 640
        },
        "times": [
          2,
          7,
          12
        ],
        "quality": "high"
      }
    ]
  },
  "command": "-ss 2 -i {{in_source}} -ss 7 -i {{in_source}} -ss 12 -i {{in_source}} -map 0:v:0 -vf scale=640:7680:force_original_aspect_ratio=decrease:force_divisible_by=2 -frames:v 1 -q:v 2 {{out_thumbnail_1}} -map 1:v:0 -vf scale=640:7680:force_original_aspect_ratio=decrease:force_divisible_by=2 -frames:v 1 -q:v 2 {{out_thumbnail_2}} -map 2:v:0 -vf scale=640:7680:force_original_aspect_ratio=decrease:force_divisible_by=2 -frames:v 1 -q:v 2 {{out_thumbnail_3}}",
  "input_files": {
    "in_source": "https://videxo.io/samples/talk.mp4"
  },
  "output_files": {
    "out_thumbnail_1": "thumbnail_1.jpg",
    "out_thumbnail_2": "thumbnail_2.jpg",
    "out_thumbnail_3": "thumbnail_3.jpg"
  },
  "ffmpeg_command": "ffmpeg -ss 2 -i https://videxo.io/samples/talk.mp4 -ss 7 -i https://videxo.io/samples/talk.mp4 -ss 12 -i https://videxo.io/samples/talk.mp4 -map 0:v:0 -vf scale=640: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=640: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=640:7680:force_original_aspect_ratio=decrease:force_divisible_by=2 -frames:v 1 -q:v 2 thumbnail_3.jpg",
  "steps": [
    {
      "tool": "ffmpeg",
      "inputs": [
        "source"
      ],
      "outputs": [
        "thumbnail"
      ],
      "command": "ffmpeg -ss 2 -i https://videxo.io/samples/talk.mp4 -ss 7 -i https://videxo.io/samples/talk.mp4 -ss 12 -i https://videxo.io/samples/talk.mp4 -map 0:v:0 -vf scale=640: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=640: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=640:7680:force_original_aspect_ratio=decrease:force_divisible_by=2 -frames:v 1 -q:v 2 thumbnail_3.jpg"
    }
  ],
  "webhook_url": null,
  "metadata": {},
  "progress": null,
  "error": null,
  "outputs": [],
  "usage": null,
  "created_at": "2026-11-04T12:00:00.000Z",
  "started_at": null,
  "finished_at": null
}

Responses

Responses
Status	Body	When
200	Job	The job this Idempotency-Key made earlier (same endpoint and body).
202	Job	The job, queued.
400	Problem	invalid_request (with `errors`) or command_invalid (with `problems`)
401	Problem	authentication_failed (missing_api_key, invalid_api_key, api_key_revoked, api_key_expired)
402	Problem	usage_cap_reached or out_of_credits
403	Problem	permission_denied (account_disabled, token_scope)
404	Problem	not_found (upload)
409	Problem	conflict (idempotency_key_reused)
413	Problem	limit_exceeded (request_body_size): the body is larger than 512 KB
415	Problem	invalid_request (not_json): the body is not sent as application/json
429	Problem	rate_limited, with Retry-After in seconds
500	Problem	internal_error
503	Problem	service_unavailable (temporary): the account's free credits are still being granted, or a part of the service did not answer