---
title: "Get a video thumbnail or animated preview"
method: GET
path: "/v1/videos/{id}/thumbnail"
tags: ["Videos"]
---

# Get a video thumbnail or animated preview

`GET /v1/videos/{id}/thumbnail`

Returns a signed CDN URL for a still image (jpg/png/webp) or animated preview (gif/mp4) of a video at a time on the video's playback timeline (cuts applied, cumulative across clips). By default returns a 302 redirect — set `?response=json` to get `{url}` JSON instead.

## Path parameters

- `id` string, required — Unique video identifier

## Query parameters

- `format` 'jpg' | 'png' | 'webp' | 'gif' | 'mp4' — Output format. Defaults to jpg.
- `startTimeMs` integer — Frame offset in ms on the playback timeline (cuts applied) — clip-relative for the clip thumbnail, video-relative (cumulative across clips) for the video thumbnail. Defaults to 0.
- `durationMs` integer — Duration of the animated preview in ms. Only valid when format is gif or mp4.
- `fps` number — Frame rate for MP4 previews. Must be 1, 2, 5, 10, or 30. Defaults to 30.
- `width` integer — Output width in pixels. The thumbnail keeps the video's aspect ratio; a missing side is derived from it.
- `height` integer — Output height in pixels. Derived from the video's aspect ratio when omitted.
- `download` union — Suggest a download disposition on the signed URL.
  - 'true'
  - 'false'
- `response` 'json' — Set to 'json' to receive `{url}` instead of the default 302 redirect.

## Response `200`

Returned when `?response=json` is set

- ThumbnailResponse — Signed CDN URL for the requested thumbnail. Returned only when `?response=json` is set; otherwise the endpoint redirects to the URL with a 302.
  - `url` string, uri, required

## Other responses

- `302` — Redirect to the signed CDN URL
- `400` — The request was malformed or contained invalid parameters.
- `401` — Authentication is required. Provide a valid API key.
- `403` — You don't have permission to access this resource.
- `404` — The requested resource was not found.
- `429` — You have exceeded the rate limit. Please slow down.
- `500` — An unexpected error occurred
- `501` — The requested operation is not implemented.

## Changes

- **2026-09-02** `cd69045c703a` — 1 warning, 1 info
  - deleted the `query` request parameter `inpointMs`
  - added the new optional `query` request parameter `startTimeMs`

[Change history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/thumbnail/get.md)

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) · [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withchima/tella-public-api/revisions/841897ed76ba/schema)