Video Thumbnail Generator creates a thumbnail clip from a source video and returns a job you can poll for completion. Send either a video file or a video_url, then optionally set size, duration, and start_time to control the output clip.
Use the multipart file endpoint when you already have the video in hand, or the URL endpoint when you need ApyHub to download the source first. In both cases, the request accepts an optional persistent flag and returns a job_id immediately after submission.
When the job finishes, check the job status with job_id. The status response includes status, job_id, and, when successful, a url for the clipped video output. Failed and pending jobs also include a human-readable message.
This is useful when you need a short preview asset for a media library, product page, upload flow, or content moderation pipeline without processing video locally.
▣ ENDPOINT 01 / 03
POST
Submit generate video thumbnail job (multipart file)
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.
About this endpoint
What it does
Submits a video file to start an asynchronous video-thumbnail generation job. The request sends a multipart file plus optional job parameters, and the response returns a job identifier you can use to poll for completion.
Query Parameter(s)
Attribute
Type
Mandatory
Description
persistent
Boolean
No
Optional query flag.
Request Body
Parameter
Type
Mandatory
Description
video
String
Yes
Source video file.
size
String
No
Optional output scale WIDTHxHEIGHT (even integers, e.g. 640x360).
duration
String
No
Clip length in seconds; capped at 20. Default 2.
start_time
String
No
Seek offset in seconds (non-negative integer). Default 0.
Response
Returns a JSON object with a required job_id string field. This is the job identifier for status polling.
Parameter
Type
Mandatory
Description
job_id
String
Yes
Job identifier for status 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.
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
Submits an asynchronous job to generate a video thumbnail from a source video URL. The request body provides the source video_url and optional clip/size settings, and the response returns a job identifier you can use to poll for completion.
Query Parameter(s)
Attribute
Type
Mandatory
Description
persistent
Boolean
No
Whether the job should be persistent.
Request Body
Parameter
Type
Mandatory
Description
video_url
String
Yes
HTTP(S) URL of the source video to download and clip. Format: URI.
Seek offset in seconds (non-negative integer). Default 0.
Response
Returns a JSON object with a job_id string field — a UUID job identifier for status polling. The response is returned immediately after a successful async job submission.
Parameter
Type
Mandatory
Description
job_id
String
Yes
Job 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.
Check the status of a video thumbnail generation job by its job ID.
curl -X GET "https://api.eu.apyverse.com/apyhub/generate-video-thumbnail/jobs/:job_id"
What you'll get back
Returns a JSON object with a data object. The data object can include job_id (string), status (string: pending, successful, or failed), message (string), and url (string) when the job succeeds.
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 generate video thumbnail job by job_id and returns the job metadata in a JSON object. When the job is successful, the response includes the output url.
Path Parameter(s)
Attribute
Type
Mandatory
Description
job_id
String
Yes
Job identifier, UUID format.
Response
Returns a JSON object with a required data object field. The data object may include job_id as a UUID string, status as a string enum, message as a human-readable string, and url as a URI string when the job is successful.
Parameter
Type
Mandatory
Description
data
Object
Yes
Wrapper object containing the job status payload.
data.url
String
No
Presigned or CDN URL to the clipped video output, present when status is successful. Format: URI.
data.job_id
String
No
Job identifier. Format: UUID.
data.status
ENUM
No
Job 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.message
String
No
Human-readable status message, used 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 (successful or failed). The result field data.url is only populated once 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.