Thumbnails

Generate a custom thumbnail

POST /v1/api/{orgID}/videos/{publicID}/thumbnails

Body:

{ "width": 320, "height": 180, "timestampMs": 12000 }

Response includes a jobId and final worker url.

Poll status

GET /v1/api/thumbnails/{jobID}

When completed, use the returned url (served by the worker).

Best thumbnail

The details endpoint includes the best available thumbnail as thumbnailUrl.

For private videos, this URL is returned clean (without authentication tokens). You have two options:

1. Signing keys (recommended): Store the URL and sign it on-demand using your signing keys
2. previewToken (quick access): Use the included previewToken for immediate access

// Using signing keys (recommended for storage)
const signedUrl = `${video.thumbnailUrl}&token=${generateJWT(signingKey)}`;

// Using previewToken (expires after ~1 hour)
const signedUrl = `${video.thumbnailUrl}&token=${video.previewToken}`;

See Private Videos for signing key setup.