Outputs and lifecycle

Retrieve thumbnail files and manage their lifecycle.

Use webhooks to learn when processing finishes. Save the ID returned when you generate thumbnails to match notifications or retrieve the current state when needed.

Follow processing

Status	Meaning
`preparing`	Thumbnail generation is queued or in progress.
`ready`	Processing and publication finished; the available files can be used.
`failed`	Processing failed. Read `error.code` and `error.message`.
`expired`	Temporary output files have expired and their delivery URLs are no longer available.

Generation can finish with fewer samples than requested. Read samples to see what was produced. If no samples are published, generation fails. Correct the input or settings before generating thumbnails again.

Receive webhook notifications

Configure a webhook and verify its signature before processing notifications. Standalone thumbnail events contain the resource snapshot in data.thumbnail.

Event	Meaning
`thumbnail.created`	The thumbnail resource was created.
`thumbnail.ready`	The available thumbnails and their index were published.
`thumbnail.failed`	Processing failed.
`thumbnail.expired`	Temporary output files expired.
`thumbnail.deleted`	The resource was deleted, by you or on its scheduled `delete_at`.

Webhooks can arrive more than once or out of order. Use the thumbnail ID to match notifications and retrieve the current state when needed.

Thumbnails created as Asset outputs use aop_ IDs and asset.output.* events with the resource at data.output.details. Use the Asset outputs API to manage those outputs.

Retrieve thumbnails

Retrieve thumbnails by ID when you need the current status or fresh temporary file URLs. Run this on your server using the client configured in the quickstart. Replace the example ID with the one you saved.

const result = await client.thumbnails.retrieve(
    'thm_2G6MJiNz71bHQGNzGwKx5cJwPFS',
);

console.log(result.status, result.files, result.samples);
result = client.thumbnails.retrieve(
    "thm_2G6MJiNz71bHQGNzGwKx5cJwPFS",
)

print(result.status, result.files, result.samples)
$result = $client->thumbnails->retrieve(
    'thm_2G6MJiNz71bHQGNzGwKx5cJwPFS',
);

var_dump($result->status, $result->files, $result->samples);
result, err := client.Thumbnails.Get(
	context.Background(),
	"thm_2G6MJiNz71bHQGNzGwKx5cJwPFS",
)
if err != nil {
	log.Fatal(err)
}

fmt.Println(result.Status, result.Files, result.Samples)

List Thumbnails lets you find thumbnails by Source, output storage, status, or creation time.

Use the files

The files collection includes images or sprite sheets and a WebVTT index. Use each file's kind to identify it:

Kind	Contents
`image`	One thumbnail image.
`sprite`	A sheet containing several thumbnails.
`vtt`	A timeline index that points to images and, for sprites, their tile coordinates.

Use an image's cdn_url for a poster or preview card. For timeline previews, pass the WebVTT file's cdn_url to your player.

Without a configured CDN, use the returned url. These temporary links expire after up to ten minutes; retrieve the thumbnails again to refresh them.

Expiry and deletion

Thumbnails in Chunkify temporary storage expire 24 hours after publication, as shown by expires_at. They then become expired and their files are removed. Thumbnails in your storage don't expire.

Chunkify deletes standalone thumbnail records automatically. delete_at shows when, and a thumbnail.deleted event is sent:

Status	Record deleted
`expired`	3 days after the files expire.
`ready` in your storage	When your team's data retention period ends.
`failed`	When your team's data retention period ends.

The data retention period is counted from when the thumbnails were requested. A record is always kept for at least 3 days after it becomes ready or fails.

Automatic deletion removes only the Chunkify record; it never deletes files in your storage. Thumbnails owned by an Asset follow that Asset instead.