---
title: "Get a clip storyboard"
method: GET
path: "/v1/videos/{id}/clips/{clipId}/storyboard"
tags: ["Clips"]
---

# Get a clip storyboard

`GET /v1/videos/{id}/clips/{clipId}/storyboard`

## Request

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

Returns a signed 4x4 WebP storyboard whose 16 tiles are sampled evenly across the requested window (`durationMs`/16 apart; every 5 seconds for the default 80s window) from a rendered clip, including its layouts, b-roll, zooms, and masks. `startTimeMs` is on the clip's playback timeline (cuts applied). Only `startTimeMs` and `durationMs` control the storyboard; tile count, dimensions, and format are fixed. By default returns a 302 redirect — set `?response=json` to get `{url, columns, rows, intervalMs}` JSON instead.

## Path parameters

- `id` string, required: Video identifier
- `clipId` string, required: Clip identifier

## Query parameters

- `startTimeMs` integer: Start time in ms on the selected target's playback timeline. Defaults to 0.
- `durationMs` integer: Storyboard window duration in ms. Defaults to 80000; the selected target's remaining duration may shorten it. Pass the target's full duration to sample it end to end.
- `response` 'json': Set to 'json' to receive `{url, columns, rows, intervalMs}` instead of the default 302 redirect.

## Response `200`

Returned when `?response=json` is set

- StoryboardResponse: Signed CDN URL plus the grid layout of the requested 4x4 WebP storyboard. Returned only when `?response=json` is set; otherwise the endpoint redirects to the URL with a 302.
  - `columns` integer, required: Tiles per row
  - `intervalMs` integer, required: Spacing between tiles in ms. Tile i (row-major) shows the frame at `startTimeMs + i * intervalMs`.
  - `rows` integer, required: Tile rows
  - `url` string, uri, required: Signed CDN URL of the WebP sheet

## Other responses

- `302`: Redirect to the signed storyboard 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

> 72 revisions in range; 1 not diffed.

- **2026-09-28** `ac47c99c144f`: 9 warning
  - added the new `edit_conflict` enum value to the `error` response property for the response status `400`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `401`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `403`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `404`
  - …5 more
- **2026-09-09** `6b1132ef42fb`: 14 warning, 2 info
  - added the new `conflict` enum value to the `error` response property for the response status `400`
  - added the new `conflict` enum value to the `error` response property for the response status `401`
  - added the new `conflict` enum value to the `error` response property for the response status `403`
  - added the new `conflict` enum value to the `error` response property for the response status `404`
  - …12 more
- **2026-09-02** `cd69045c703a`: 1 warning, 5 info
  - deleted the `query` request parameter `inpointMs`
  - added the new optional `query` request parameter `startTimeMs`
  - for the `query` request parameter `durationMs`, the max was increased from `80000.00` to `2147483647.00`
  - added the required property `columns` to the response with the `200` status
  - …2 more

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/storyboard/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/ca74daaf9201?raw)