Generate individual images or sprite sheets from a Source. Each accepted request creates a new resource. Processing continues after the response.
POST
/thumbnails
Authorization
Authorization
header
string
required
Enter the project access token with the Bearer prefix, e.g. "Bearer project_access_token"
Bodyapplication/json
source_id
string
required
SourceId identifies a video Source in this Project.
timestamps
number[]
required
Timestamps specifies 1 to 100 Source-relative target times in seconds. Every time must be within the selected range. Repeated targets produce separate outputs.
count
integer
Count specifies 1 to 100 thumbnails at the middle of equal sections of the selected range.
Required range: 1 <= x <= 100
format
default: "jpeg"
string
Format specifies the image encoding.
Available options:
jpegwebp
metadata
object
Metadata attaches string values to this request. The serialized object may contain at most 2048 bytes.
output
default: "images"
string
Output specifies individual images or automatically arranged sprite sheets.
Available options:
imagessprites
range
object
Range limits sampling to part of the Source. Defaults to the whole Source duration.
end
number
End specifies the exclusive upper bound in seconds. Defaults to the Source duration.
start
number
Start specifies the inclusive lower bound in seconds. Defaults to zero.
Required range: x >= 0
size
default: 320
integer
Size specifies the maximum image or tile edge in pixels, from 64 to 1920. Defaults to 320. Odd sizes are supported. Preserves display aspect ratio without cropping or upscaling.
Required range: 64 <= x <= 1920
storage
object
Storage overrides the Project output destination and names the output files. Source storage remains independent.
id
string
Id identifies output Storage in this Project. Omit to use the Project default.
path
string
Path specifies the output filename template relative to the selected Storage base_prefix. Required for customer storage; generated for Chunkify temporary storage.
The filename must contain one %05d placeholder, replaced by the image or sprite sheet number starting at 1, and end in .jpg for jpeg or .webp for webp.
The WebVTT file uses the filename without the placeholder and its adjacent separator, such as thumb.vtt for thumb-%05d.jpg. The combined path may contain at most 1024 bytes.
count
integer
required
Count specifies 1 to 100 thumbnails at the middle of equal sections of the selected range.
Required range: 1 <= x <= 100
source_id
string
required
SourceId identifies a video Source in this Project.
format
default: "jpeg"
string
Format specifies the image encoding.
Available options:
jpegwebp
metadata
object
Metadata attaches string values to this request. The serialized object may contain at most 2048 bytes.
output
default: "images"
string
Output specifies individual images or automatically arranged sprite sheets.
Available options:
imagessprites
range
object
Range limits sampling to part of the Source. Defaults to the whole Source duration.
end
number
End specifies the exclusive upper bound in seconds. Defaults to the Source duration.
start
number
Start specifies the inclusive lower bound in seconds. Defaults to zero.
Required range: x >= 0
size
default: 320
integer
Size specifies the maximum image or tile edge in pixels, from 64 to 1920. Defaults to 320. Odd sizes are supported. Preserves display aspect ratio without cropping or upscaling.
Required range: 64 <= x <= 1920
storage
object
Storage overrides the Project output destination and names the output files. Source storage remains independent.
id
string
Id identifies output Storage in this Project. Omit to use the Project default.
path
string
Path specifies the output filename template relative to the selected Storage base_prefix. Required for customer storage; generated for Chunkify temporary storage.
The filename must contain one %05d placeholder, replaced by the image or sprite sheet number starting at 1, and end in .jpg for jpeg or .webp for webp.
The WebVTT file uses the filename without the placeholder and its adjacent separator, such as thumb.vtt for thumb-%05d.jpg. The combined path may contain at most 1024 bytes.
timestamps
number[]
Timestamps specifies 1 to 100 Source-relative target times in seconds. Every time must be within the selected range. Repeated targets produce separate outputs.
Responses
application/json
data
object
required
Data contains the thumbnail resource.
asset_id
object
required
AssetId identifies the owning Asset for Workflow outputs, or null for standalone requests.
created_at
string
date-time
required
CreatedAt records when the request was accepted.
files
object[]
required
Files contains all published images or sheets and the WebVTT index. Empty while preparing.
kind
string
required
Kind identifies an individual image, sprite sheet, or WebVTT index.
Available options:
imagespritevtt
path
string
required
Path specifies the file relative to storage_prefix.
size
integer
required
Size specifies the measured encoded file size in bytes.
Required range: x >= 1
cdn_url
string
CdnUrl provides delivery through the configured CDN. Omitted without a CDN or after expiry.
height
integer
Height specifies the measured image or complete sprite canvas height. Omitted for WebVTT.
Required range: x >= 1
url
string
Url provides temporary authorized delivery. Omitted after expiry or when unavailable.
width
integer
Width specifies the measured image or complete sprite canvas width. Omitted for WebVTT.
Required range: x >= 1
id
string
required
Id identifies this thumbnail request. Standalone requests use thm_ IDs; Asset-owned outputs use aop_ IDs.
Examples:
thm_example
metadata
object
required
Metadata contains the accepted string metadata.
samples
object[]
required
Samples contains published thumbnails ordered by timestamp. Empty while preparing. A ready resource may contain fewer samples than requested.
height
integer
required
Height specifies this image or tile height in pixels.
Required range: x >= 1
path
string
required
Path identifies the image or sprite sheet in files.
timestamp
number
required
Timestamp specifies the measured Source-relative presentation time of the selected frame in seconds. Compatible cached inputs use millisecond timestamps, which can select a neighboring frame compared with the original Source.
Required range: x >= 0
width
integer
required
Width specifies this image or tile width in pixels.
Required range: x >= 1
crop
object
Crop specifies the tile origin in its sprite sheet. Omitted for individual images; width and height give the tile dimensions.
x
integer
required
X specifies the left edge in pixels.
Required range: x >= 0
y
integer
required
Y specifies the top edge in pixels.
Required range: x >= 0
settings
object
required
Settings contains the accepted sampling and output settings.
format
string
required
Format specifies the image encoding.
Available options:
jpegwebp
output
string
required
Output specifies individual images or automatically arranged sprite sheets.
Available options:
imagessprites
range
object
required
Range contains the accepted sampling boundaries.
end
number
required
End specifies the exclusive upper bound in seconds.
start
number
required
Start specifies the inclusive lower bound in seconds.
Required range: x >= 0
size
integer
required
Size specifies the accepted maximum image or tile edge in pixels.
Required range: 64 <= x <= 1920
timestamps
number[]
required
Timestamps specifies 1 to 100 Source-relative target times in seconds. Every time must be within the selected range. Repeated targets produce separate outputs.
count
integer
Count specifies 1 to 100 thumbnails at the middle of equal sections of the selected range.
Required range: 1 <= x <= 100
count
integer
required
Count specifies 1 to 100 thumbnails at the middle of equal sections of the selected range.
Required range: 1 <= x <= 100
format
string
required
Format specifies the image encoding.
Available options:
jpegwebp
output
string
required
Output specifies individual images or automatically arranged sprite sheets.
Available options:
imagessprites
range
object
required
Range contains the accepted sampling boundaries.
end
number
required
End specifies the exclusive upper bound in seconds.
start
number
required
Start specifies the inclusive lower bound in seconds.
Required range: x >= 0
size
integer
required
Size specifies the accepted maximum image or tile edge in pixels.
Required range: 64 <= x <= 1920
timestamps
number[]
Timestamps specifies 1 to 100 Source-relative target times in seconds. Every time must be within the selected range. Repeated targets produce separate outputs.
source_id
object
required
SourceId identifies the input Source, or null if it has been deleted.
status
string
required
Status is ready only after processing and publication finish. Temporary outputs become expired after their retention period.
Available options:
preparingreadyfailedexpired
storage_id
string
required
StorageId identifies the accepted output Storage.
storage_path
object
required
StoragePath specifies the accepted filename template relative to the Storage base_prefix, or null when Chunkify generated the file names.
storage_prefix
string
required
StoragePrefix specifies the complete output folder saved at creation. File and sample paths are relative to this folder.
updated_at
string
date-time
required
UpdatedAt records the last lifecycle update.
created_by_token_id
string
CreatedByTokenId specifies the Project token used to create the resource. It remains set after the token is revoked.
Omitted for dashboard requests, MCP OAuth connections, Workflow actions, and unknown creators.
Examples:
tok_2G6MJiNz71bHQGNzGwKx5cJwPFS
created_by_user_id
string
CreatedByUserId specifies the team member who created the resource.
Omitted for Workflow actions, unknown creators, and deleted accounts.
Examples:
u_2G6MJiNz71bHQGNzGwKx5cJwPFS
created_via
string
CreatedVia specifies how the resource was created: api for API requests, dashboard for the Chunkify dashboard, mcp for MCP clients, and workflow for Workflow actions.
Omitted when the creator is unknown.
Available options:
apidashboardmcpworkflow
Examples:
api
delete_at
string
date-time
DeleteAt specifies when this standalone request is deleted: three days after its temporary output expires, otherwise when the team's data retention period ends, counted from when the request was accepted, and no sooner than three days after it finished. It does not delete files in customer-owned Storage. Omitted while preparing and for Asset-owned thumbnails, which follow their Asset.
error
object
Error explains a failed request. Omitted otherwise.
code
string
required
Code identifies the processing failure.
message
string
required
Message explains the processing failure.
expires_at
string
date-time
ExpiresAt specifies when temporary output files expire. Omitted for customer output Storage.
ready_at
string
date-time
ReadyAt records when the complete available set was published. Omitted before publication.
status
"success"
string
required
Status is success for a successful request.
Thumbnail accepted for processing.
application/json
error
object
required
code
400
integer
required
Code is the HTTP status code
Examples:
400
message
string
required
Message is a human-readable error description
Examples:
Invalid request parameters
type
"ValidationError"
string
required
Type indicates the error category
Available options:
ValidationError
status
"error"
string
required
Status indicates the response status "error"
The request, Source or output destination is invalid or unavailable.
application/json
error
object
required
Error response details
code
401
integer
required
Code is the HTTP status code
Examples:
401
message
string
required
Message is a human-readable error description
Examples:
Authentication error: invalid token or subscription inactive
type
"AuthenticationError"
string
required
Type indicates the error category
Available options:
AuthenticationError
status
"error"
string
required
Status indicates the response status "error"
Authentication error
application/json
error
object
required
Error response details
code
403
integer
required
Code is the HTTP status code
Examples:
403
message
string
required
Message is a human-readable error description
Examples:
Unauthorized to perform this action
type
"ForbiddenError"
string
required
Type indicates the error category
Available options:
ForbiddenError
status
"error"
string
required
Status indicates the response status "error"
Processing requires an active subscription, a permitted Source size, and enough credits for the full request.