apyhub
Back
▣ FILE CONVERSION · FILE MANIPULATION

Generate Thumbnail from Video Job API

Hosted on ApyHub

What it does

Video Thumbnail Generator creates a thumbnail frame from a video you upload or reference by URL. Send a video file or a video_url, optionally set time to choose the frame position in seconds and size to request an output in WIDTHxHEIGHT with even integers.

Submit the job and get back a job_id immediately. Poll GET /jobs/:job_id to check whether the job is pending, successful, or failed. When the job finishes successfully, the status response includes a url for the generated output. If the job is still running or has failed, the response also includes a human-readable message.

Use Video Thumbnail Generator when you need a preview image or frame capture for a media library, upload flow, content management system, or video catalog. The API supports asynchronous processing, so you can accept larger files without blocking the request that starts the job.

If you need the result to remain available, set persistent on submission. Otherwise, use the returned url from the job status response to retrieve the generated thumbnail output.

▣ ENDPOINT 01 / 03
POST
Submit video thumbnail job (multipart file)
https://api.eu.apyhub.com/apyhub/generate-video-thumbnail-job/file-to-json

QUICKSTART

GUIDE

Quickstart

Upload a video file to start an async thumbnail-generation job. video is required; persistent is an optional query flag and is omitted here.

curl -X POST "https://api.eu.apyhub.com/apyhub/generate-video-thumbnail-job/file-to-json" \
  -H "apy-token: $APY_TOKEN" \
  -F "video=@/path/to/video.mp4" '

What you'll get back

Returns a JSON object with a required job_id string field, which is a UUID for polling the job status.

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
TRY ITLIVE · 400 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.
body*

About this endpoint

What it does

Submits a video file as a multipart upload to start an asynchronous video thumbnail job. The endpoint returns a job identifier immediately so the result can be polled later.

Query Parameter(s)

AttributeTypeDescription
persistentBooleanControls whether the job should be persistent.

Request Body

ParameterTypeDescription
videoBinaryVideo file upload in binary format.
sizeStringThumbnail size.
timeStringTime value used for thumbnail generation.

Response

Returns a JSON object with a job_id string field in UUID format. This is the job identifier returned immediately after successful submission.

ParameterTypeDescription
job_idStringJob identifier for status polling; UUID format.

Notes

This endpoint kicks off an async job and returns immediately with a job identifier; the actual work runs in the background. Pair this call with the corresponding job_check endpoint — poll that until the status reaches a terminal state to retrieve the result. Use the returned job_id value to poll status.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 02 / 03
POST
Submit video thumbnail job (source URL)
https://api.eu.apyhub.com/apyhub/generate-video-thumbnail-job/url-to-json

QUICKSTART

GUIDE

Quickstart

Submit a video URL to start generating a thumbnail.

curl -X POST "https://api.eu.apyhub.com/apyhub/generate-video-thumbnail-job/url-to-json" \
  -H "apy-token: $APY_TOKEN" \
  -d '{
    "video_url": "https://assets.apyhub.com/samples/sample.mp4"
  }'

What you'll get back

Returns a JSON object with a job_id string field — the UUID of the async job you can use for status polling.

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
TRY ITLIVE · 400 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
body*
Optional output size WIDTHxHEIGHT (even integers).
Frame position in seconds (positive integer). Default 1.

About this endpoint

What it does

Submits a video thumbnail generation job using a source video URL and returns a job identifier immediately. The actual thumbnail generation runs asynchronously.

Query Parameter(s)

AttributeTypeDescription
persistentBooleanWhether the generated result should be persisted.

Request Body

ParameterTypeDescription
sizeStringOptional output size in WIDTHxHEIGHT format with even integers.
timeStringFrame position in seconds as a positive integer. Default is 1.
video_urlStringSource video URL. Must be a URI.

Response

Returns a JSON object with a job_id string field — a UUID job identifier for status polling. The response is not wrapped in data.

ParameterTypeDescription
job_idStringJob identifier for status polling.

Notes

This endpoint kicks off an async job and returns immediately with a job identifier; the actual work runs in the background. Pair this call with the corresponding job_check endpoint — poll that until the status reaches a terminal state to retrieve the result. Extract the job_id field from the response.

▣ ENDPOINT 03 / 03
GET
Check video thumbnail job status
https://api.eu.apyhub.com/apyhub/generate-video-thumbnail-job/jobs/:job_id

QUICKSTART

GUIDE

Quickstart

Fetch the status and output URL for a video thumbnail generation job by its job ID.

curl -X GET "https://api.eu.apyhub.com/apyhub/generate-video-thumbnail-job/jobs/:job_id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a data object. Inside data, job_id is the job UUID, status is one of pending, successful, or failed, message is a human-readable status string, and url is present when the job is successful.

{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "successful",
    "message": "Thumbnail generated successfully",
    "url": "https://assets.apyhub.com/samples/sample.mp4"
  }
}
TRY ITLIVE · 5 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Checks the status of a video thumbnail generation job identified by job_id and returns the job record inside a data object. When the job has completed successfully, the response includes the output url.

Path Parameter(s)

AttributeTypeDescription
job_idStringJob identifier in UUID format.

Response

Returns a JSON object with a data object field. The data object contains the job job_id string, status string, and may include a url string when the job is successful; it may also include a human-readable message string.

ParameterTypeDescription
dataObjectJob details object. Includes job_id, status, and may include url when status is successful; may include message for pending or failed responses.
data.urlStringPresigned or CDN URL to the job output. Present when status is successful.
data.job_idStringJob identifier in UUID format.
data.statusENUMJob status. Allowed values: pending, successful, failed. pending while submitted or processing. successful when output is ready. failed when the worker marked the job failed.
data.messageStringHuman-readable status message for pending or failed responses.

Notes

Poll this endpoint with the job_id returned by the submit call. The data.status field cycles through pending before reaching a terminal state of successful or failed. The result field is data.url, and it is only populated once data.status is successful; treat it as absent otherwise.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.

Similar APIs

Closest matches in the catalog based on this service.

CALLGenerate Thumbnail from Video APIApyHubCALLGenerate Image Thumbnails APIApyHubCALLGenerate GIF from Video Job APIApyHubCALLGenerate Watermark For Videos Job APIApyHub

From the blog

Reads that touch this API.

Top Video Processing Jobs (2026): Streamline with Job-Based APIAug 7, 2026Video Thumbnails for SEO: How They Lift CTR, and How to Generate Them with an APISep 22, 2026Generating Video Thumbnails with ApyHub’s API (Go Guide)Aug 7, 2026Exploring the Top Video Thumbnail ( Preview) APIsJul 9, 2026