apyhub
▣ 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)
http://localhost:8080/apyhub/generate-video-thumbnail-job-api/file-to-json
QUICKSTARTGUIDE

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 "http://localhost:8080/apyhub/generate-video-thumbnail-job-api/file-to-json" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"video":"<base64-or-file-content>"}'

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)

AttributeTypeMandatoryDescription
persistentBooleanNoControls whether the job should be persistent.

Request Body

ParameterTypeMandatoryDescription
videoStringYesVideo file upload in binary format.
sizeStringNoThumbnail size.
timeStringNoTime 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.

ParameterTypeMandatoryDescription
job_idStringYesJob 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.

Query parameters

Name
Type
Description
persistentOPTIONAL
boolean
—

Body

Name
Type
Description
bodyREQUIRED
object
—

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

▣ ENDPOINT 03 / 03
POST
Submit video thumbnail job (source URL)
http://localhost:8080/apyhub/generate-video-thumbnail-job-api/url-to-json
QUICKSTARTGUIDE

Quickstart

Submit a video URL to start generating a thumbnail.

curl -X POST "http://localhost:8080/apyhub/generate-video-thumbnail-job-api/url-to-json" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -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)

AttributeTypeMandatoryDescription
persistentBooleanNoWhether the generated result should be persisted.

Request Body

ParameterTypeMandatoryDescription
sizeStringNoOptional output size in WIDTHxHEIGHT format with even integers.
timeStringNoFrame position in seconds as a positive integer. Default is 1.
video_urlStringYesSource 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.

ParameterTypeMandatoryDescription
job_idStringYesJob 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.

Query parameters

Name
Type
Description
persistentOPTIONAL
boolean
—

Body

Name
Type
Description
bodyREQUIRED
object
—
▣ ENDPOINT 02 / 03
GET
Check video thumbnail job status
http://localhost:8080/apyhub/generate-video-thumbnail-job-api/jobs/:job_id
QUICKSTARTGUIDE

Quickstart

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

curl -X GET "http://localhost:8080/apyhub/generate-video-thumbnail-job-api/jobs/:job_id"

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)

AttributeTypeMandatoryDescription
job_idStringYesJob 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.

ParameterTypeMandatoryDescription
dataObjectNoJob details object. Includes job_id, status, and may include url when status is successful; may include message for pending or failed responses.
data.urlStringNoPresigned or CDN URL to the job output. Present when status is successful.
data.job_idStringNoJob identifier in UUID format.
data.statusENUMNoJob 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.messageStringNoHuman-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.

Path parameters

Name
Type
Description
job_idREQUIRED
string
—
▣ 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.

Product
CatalogPricingBecome a providerStatus (opens in new tab)
Company
AboutBlogCareers (opens in new tab)Contact
Legal
Terms of ServicePrivacy PolicyProvider terms
© 2026 APYHUB · BUILT FOR DEVELOPERS