apyhub
▣ FILE CONVERSION · FILE MANIPULATION

Generate Video Thumbnail Job API

Hosted on ApyHub

What it does

Video Thumbnail Generator clips a source video into a short output video and lets you set the starting point, clip length, and optional output size.

Send either a video file or a video_url, then choose start_time in seconds, duration in seconds, and an optional size in WIDTHxHEIGHT format. duration is capped at 20 seconds, and start_time defaults to 0. The file upload endpoint accepts a multipart video field; the URL endpoint downloads the video from an HTTP(S) source and processes it asynchronously.

When the job is accepted, you get back a job_id for polling. Use GET /jobs/:job_id to check status: pending, successful, or failed. On success, the job response includes a url to the clipped video output. If the job is still running or fails, the response includes the job status and a human-readable message.

Use Video Thumbnail Generator when you need short preview clips for media libraries, upload workflows, content moderation queues, or sharing a specific segment of a longer video.

▣ ENDPOINT 01 / 03
POST
Submit generate video thumbnail job (multipart file)
http://localhost:8080/apyhub/generate-video-thumbnail-job/file-to-json
QUICKSTARTGUIDE

Quickstart

Upload a video file to start an async thumbnail-generation job.

curl -X POST "http://localhost:8080/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 job_id string field — a UUID you can use to poll for 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*
Optional output scale WIDTHxHEIGHT (even integers, e.g. 640x360).
Source video file.
Clip length in seconds; capped at 20. Default 2.
Seek offset in seconds (non-negative integer). Default 0.

About this endpoint

What it does

Submits a video file to start an asynchronous video thumbnail generation job. The endpoint accepts a multipart file upload plus optional job parameters and returns a job identifier immediately.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoWhether the job should persist.

Request Body

ParameterTypeMandatoryDescription
videoStringYesSource video file. Binary upload (format: binary).
sizeStringNoOptional output scale in WIDTHxHEIGHT format using even integers, for example 640x360.
durationStringNoClip length in seconds. Default 2; capped at 20.
start_timeStringNoSeek offset in seconds as a non-negative integer. Default 0.

Response

Returns a JSON object with a job_id string field, formatted as a UUID. This is the identifier for polling job status after submission.

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. Extract the job_id field from the response.

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 generate video thumbnail job (source URL)
http://localhost:8080/apyhub/generate-video-thumbnail-job/url-to-json
QUICKSTARTGUIDE

Quickstart

Start a video thumbnail job by sending the source video URL.

curl -X POST "http://localhost:8080/apyhub/generate-video-thumbnail-job/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 job identifier you can use to poll for 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 scale WIDTHxHEIGHT (even integers).
Clip length in seconds; capped at 20. Default 2.
HTTP(S) URL of the source video to download and clip.
Seek offset in seconds (non-negative integer). Default 0.

About this endpoint

What it does

Submits an async job to generate a thumbnail from a source video URL. The request body supplies the source video_url and optional clipping/resize parameters, and the response returns a job identifier for later polling.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoWhether the job should be persisted.

Request Body

ParameterTypeMandatoryDescription
video_urlStringYesHTTP(S) URL of the source video to download and clip. Format: URI.
sizeStringNoOptional output scale WIDTHxHEIGHT (even integers). Example: 640x360.
durationStringNoClip length in seconds; capped at 20. Default: 2. Example: 8.
start_timeStringNoSeek offset in seconds (non-negative integer). Default: 0. Example: 2.

Response

Returns a JSON object with a required job_id string field — the job identifier used for status polling. The response is returned immediately after successful async job submission and is not wrapped in data.

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 from the response.

Query parameters

Name
Type
Description
persistentOPTIONAL
boolean
—

Body

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

Quickstart

Check the status of a thumbnail generation job by its job ID.

curl -X GET "http://localhost:8080/apyhub/generate-video-thumbnail-job/jobs/:job_id/jobs/123e4567-e89b-12d3-a456-426614174000" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a top-level data object. The data object can include url when the job is successful, plus job_id, status, and message depending on the job state.

{
  "data": {
    "job_id": "123e4567-e89b-12d3-a456-426614174000",
    "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 submitted video thumbnail generation job by job ID. It returns a JSON object containing a data object with the job’s job_id, current status, and related result/status fields.

Path Parameter(s)

AttributeTypeMandatoryDescription
job_idStringYesJob identifier in UUID format.

Response

Returns a JSON object with a data object field. Inside data, job_id is a UUID string, status is a string enum (pending, successful, failed), message is a string, and url is a URI string that is present when the status is successful.

ParameterTypeMandatoryDescription
dataObjectYesContains the job status information.
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.
data.urlStringNoPresigned or CDN URL to the clipped video output. Present when status is successful; URI format.

Notes

This is a job status check endpoint. Poll it using the job_id from the corresponding job submission flow, and read the result from data.url once data.status becomes successful.

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