---
title: "Get a frame or preview of a Tella Motion document"
method: GET
path: "/v1/motion/documents/{id}/thumbnail"
tags: ["Tella Motion"]
---

# Get a frame or preview of a Tella Motion document

`GET /v1/motion/documents/{id}/thumbnail`

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/motion/documents/{id}/thumbnail`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/motion/documents/:id/thumbnail/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns a signed CDN URL for a still image (jpg/png/webp) or animated preview (gif/mp4) of the document on its own, at a time on its own clock: any document you can edit, also one no video plays yet. Width and height follow the document's canvas; a time at or past its end shows its end. By default returns a 302 redirect — set `?response=json` to get `{url}` JSON instead.

## Path parameters

- `id` string, required: Tella Motion document ID (ffd_…), from `GET /v1/motion/documents`.

## 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.
- `409`: The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles.
- `429`: You have exceeded the rate limit. Please slow down.
- `500`: An unexpected error occurred
- `501`: The requested operation is not implemented.
- `503`: A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay.

## Changes

> 65 revisions in range; 1 not diffed.

- **2026-10-27** `de97e9827c3c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/motion/documents/: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.dev/withchima/apis/tella-public-api/revisions/0cc3fcd307ad?raw)