---
title: "Video"
description: "Video — Cloudflare Stream specialization of a file row. Surfaced
alongside its file data via the filtered `/api/videos` endpoint.
Keyed by its own `vid_…` id, with a unique 1:1 FK to the underlying
file (`fileId`).

Transcoding is async inside CF. The row starts in `processing` and
lazy-reconciles to `ready`/`error` on subsequent `GET /api/videos/:id`
calls (the service hits CF Stream's status API and updates the row)."
section: "Reference"
group: "Types"
order: 251
---

## Definition

```ts
interface Video {
  id: string;
  fileId: string;
  workspaceId: string;
  cfStreamUid: string;
  transcodingStatus: "error" | "ready" | "queued" | "processing";
  transcodingError: string | null;
  duration: number | null;
  width: number | null;
  height: number | null;
  size: number | null;
  metadata: any;
  playbackUrl: string;
  thumbnailUrl: string;
  signedToken: string | null;
}
```

## Fields

| Field               | Type                                             | Notes                                                                                                                                                                   |
| ------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | `string`                                         | `readonly` `required` — The video's prefixed ID.                                                                                                                        |
| `fileId`            | `string`                                         | `required` — Underlying file row backing this video (1:1).                                                                                                              |
| `workspaceId`       | `string`                                         | `required` — Workspace that owns the video.                                                                                                                             |
| `cfStreamUid`       | `string`                                         | `required` — Cloudflare Stream UID used to build playback URLs.                                                                                                         |
| `transcodingStatus` | `"error" \| "ready" \| "queued" \| "processing"` | `required` — Async transcoding lifecycle: 'queued' → 'processing' → 'ready', or 'error'.                                                                                |
| `transcodingError`  | `string \| null`                                 | `required` — Error message from CF Stream when status is 'error'.                                                                                                       |
| `duration`          | `number \| null`                                 | `required` — Duration in seconds, once CF Stream reports it.                                                                                                            |
| `width`             | `number \| null`                                 | `required` — Video width in pixels, if known.                                                                                                                           |
| `height`            | `number \| null`                                 | `required` — Video height in pixels, if known.                                                                                                                          |
| `size`              | `number \| null`                                 | `required` — Video size in bytes, if known.                                                                                                                             |
| `metadata`          | `any`                                            | `required` — Additional metadata returned by CF Stream.                                                                                                                 |
| `playbackUrl`       | `string`                                         | `required` — Cloudflare Stream HLS manifest URL                                                                                                                         |
| `thumbnailUrl`      | `string`                                         | `required` — Cloudflare Stream thumbnail URL                                                                                                                            |
| `signedToken`       | `string \| null`                                 | `required` — Signed CF Stream JWT for private playback. Pass as the `src` prop of @cloudflare/stream-react's <Stream> component. `null` when signing is not configured. |