Preview source video timestamps
Source-generated POST /assets/{asset_id}/preview reference: authentication, fields, responses, errors, and operational safeguards.
On this page
Operation
POST /assets/{asset_id}/preview
operationId: preview_video_asset_v1_assets__asset_id__preview_post
Create or reuse a labeled source-video contact sheet, without AI processing or credit charges. The cached preview counts toward storage quota and follows normal asset retention. Each cell reports the requested time and the actual displayed source frame time. Signed URLs expire independently; refresh through asset lookup. This previews the opaque source, not final alpha quality. At most 12 timestamps and 512 pixels per frame side; media budgets are published in x-animgen-media-limits.
Authentication and side effects
Use a server-side Bearer API key. Required scope: animations:read
This operation does not start paid generation. Other state changes are described above.
Parameters
| Parameter | Location | Type | Required | Constraints / default | Meaning |
|---|---|---|---|---|---|
asset_id |
path |
string |
Yes | format: uuid |
Owned public resource UUID; task, asset, and file IDs are not interchangeable. |
Request body (application/json)
Body required: true
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
max_frame_size |
integer |
No | 256 |
minimum: 32; maximum: 512 |
Maximum thumbnail side in pixels, preserving aspect ratio. |
timestamps_seconds |
array<number> |
Yes | — | minItems: 1; maxItems: 12; items: minimum: 0 |
Source timeline timestamps in request order, each strictly before the playable end. At most 12. |
Full nested schema: VideoPreviewRequest
Request example
{
"max_frame_size": 256,
"timestamps_seconds": [
0,
1,
2
]
}
Responses
| HTTP | Body | Meaning |
|---|---|---|
200 |
VideoPreviewResponse | Successful public response. Example values are illustrative. |
400 |
APIErrorEnvelope | Invalid input; correct the request before retrying. |
401 |
APIErrorEnvelope | Missing, expired, or revoked API key. |
402 |
APIErrorEnvelope | Insufficient credits; do not automatically purchase. |
403 |
APIErrorEnvelope | Account eligibility, account status, or key scope does not allow this operation. |
404 |
APIErrorEnvelope | Resource is unavailable, not owned, or its signature is invalid/expired. |
413 |
APIErrorEnvelope | Request or decoded image exceeds the configured limit. |
415 |
APIErrorEnvelope | Use supported image media types. |
422 |
APIErrorEnvelope | Decoded image dimensions exceed the allowed size. |
429 |
APIErrorEnvelope | Account-wide rate or queue limit; wait for Retry-After. |
500 |
APIErrorEnvelope | Internal failure; preserve the task/key and retry only when marked retryable. |
503 |
APIErrorEnvelope | Service/provider unavailable; retry only when error.retryable is true. |
Response headers
| HTTP | Header | Type | Meaning |
|---|---|---|---|
429 |
Retry-After |
integer |
Suggested wait in seconds; respect the server value and an overall deadline. |
503 |
Retry-After |
integer |
Suggested wait in seconds; respect the server value and an overall deadline. |
Response example
{
"cells": [
{
"index": 0,
"rect": {
"height": 256,
"width": 256,
"x": 0,
"y": 0
},
"requested_time_seconds": 0,
"source_time_seconds": 0
},
{
"index": 1,
"rect": {
"height": 256,
"width": 256,
"x": 256,
"y": 0
},
"requested_time_seconds": 1,
"source_time_seconds": 1
},
{
"index": 2,
"rect": {
"height": 256,
"width": 256,
"x": 512,
"y": 0
},
"requested_time_seconds": 2,
"source_time_seconds": 2
}
],
"height": 280,
"image": {
"byte_size": 1024,
"created_at": "2026-08-30T00:00:00Z",
"download_expires_at": "2026-08-30T01:00:00Z",
"download_url": "https://downloads.example.invalid/illustrative-asset",
"format": "video_preview",
"id": "00000000-0000-4000-8000-000000000006",
"media": null,
"mime_type": "image/png",
"object": "asset"
},
"object": "video_preview",
"source_video_asset_id": "00000000-0000-4000-8000-000000000003",
"width": 768
}
Related guides
Was this page helpful?
No search queries, code, or free text are collected. This switch controls documentation interactions only; general site analytics follow the privacy policy. Privacy policy