apyhub

Generate Thumbnail from Video Job API

What it does

Video Thumbnail lets you submit a video file or a video URL and receive a thumbnail-generation job in return. It is designed for async processing: you send the source, optionally set size and time, and poll the job until the thumbnail is ready.

Use /file-to-json when you have a multipart video upload, or /url-to-json when the source is already hosted at a video_url. Both endpoints accept an optional persistent query flag. You can also control the frame position with time and request a specific output size with size in WIDTHxHEIGHT format. The immediate response gives you a job_id for status checks.

Call GET /jobs/:job_id to check progress. The job status returns pending, successful, or failed, along with the same job_id. When the job finishes successfully, the response includes a url pointing to the generated output.

Use Video Thumbnail when you need preview images for a media library, video upload flow, content CMS, or search results page. It keeps thumbnail generation decoupled from your request/response cycle, so you can handle larger files and remote sources without blocking your app.

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

QUICKSTART

GUIDE

Quickstart

Upload a video file to start an async job that returns a job ID.

curl -X POST "https://api.eu.apyverse.com/apyhub/video-thumbnail/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 job_id string field — the UUID of the submitted job 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.
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 a video thumbnail job. The endpoint returns a job identifier immediately so you can poll for completion later.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoWhether the job should be persistent.

Request Body

ParameterTypeMandatoryDescription
videoStringYesVideo file uploaded as binary (binary format).
sizeStringNoThumbnail size.
timeStringNoTime offset for extracting the thumbnail.

Response

Returns a JSON object with a job_id string field in UUID format. This is the job identifier for status polling.

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 returned job_id field to use for polling.

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 02 / 03
POST
Submit video thumbnail job (source URL)
https://api.eu.apyverse.com/apyhub/video-thumbnail/url-to-json

QUICKSTART

GUIDE

Quickstart

Submit a video URL to start an async thumbnail job.

curl -X POST "https://api.eu.apyverse.com/apyhub/video-thumbnail/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 job identifier you can use to poll status later.

{
  "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 an async video thumbnail generation job using a source video URL. On success, it returns a job identifier that you can use to poll for completion.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoWhen provided, controls whether the job should be persistent.

Request Body

ParameterTypeMandatoryDescription
video_urlStringYesSource video URL. Must be a URI.
sizeStringNoOptional output size in WIDTHxHEIGHT format using even integers.
timeStringNoFrame position in seconds as a positive integer. Default: 1.

Response

Returns a JSON object with a job_id string field. job_id is a UUID job identifier used for status polling.

ParameterTypeMandatoryDescription
job_idStringYesJob identifier for status polling. Format: UUID.

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 job_id to track the job.

Query parameters

Name
Type
Description
persistentOPTIONAL
boolean
—

Body

Name
Type
Description
bodyREQUIRED
object
—
▣ ENDPOINT 03 / 03
GET
Check video thumbnail job status
https://api.eu.apyverse.com/apyhub/video-thumbnail/jobs/:job_id

QUICKSTART

GUIDE

Quickstart

Check the status of a thumbnail job by its job_id.

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

What you'll get back

Returns a JSON object with a data object. The data object can include job_id and status for every job, plus message for pending or failed jobs, and url when the job is successful.

{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "successful",
    "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 by job_id and returns the job record inside a data object. When the job is successful, the response also includes the output url.

Path Parameter(s)

AttributeTypeMandatoryDescription
job_idStringYesJob identifier in UUID format.

Response

Returns a JSON object with a data object field containing job_id as a UUID string, status as a string enum, and optional url and message strings. The url is present when status is successful; message is used for human-readable pending or failed states.

ParameterTypeMandatoryDescription
dataObjectNoJob status payload. Contains job_id, status, and, when the job is successful, url. Also includes message for human-readable pending or failed responses.
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.urlStringNoPresigned or CDN URL to the job output. Present when status is successful. Format: URI.
data.messageStringNoHuman-readable status for pending or failed responses.

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
CatalogPricingQuickstartBecome a providerStatus (opens in new tab)
Company
AboutBlogCareers (opens in new tab)Contact
Legal
Terms of ServicePrivacy PolicyProvider terms
© 2026 APYHUB · BUILT FOR DEVELOPERS