> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Add metadata to videos

FastPix improves video organization, search, and workflow automation by letting you attach custom key-value `metadata` to any on-demand video at upload time or update it later through the API. Include a `metadata` object in the create-media request body, and FastPix stores and returns your custom video attributes with every asset read, without changing playback behavior.

FastPix does not process `metadata` internally. The field exists to support your workflows, letting you define how content is categorized, linked, or routed downstream.

\


## Prerequisites

* A FastPix account with an active workspace ([Activate your account](/getting-started/activate-your-account))
* Your **Access Token ID** and **Secret Key** from the FastPix dashboard
* At least one on-demand video uploaded, or a ready-to-upload source URL (see [Upload videos from URL](/upload-videos/upload-videos-from-a-url))

\


## What is metadata?

`metadata` is a flat JSON object of string-based key-value pairs that FastPix attaches to a media asset. You define the schema, it can include campaign names, categories, user IDs, or workflows. FastPix stores the object and returns it on every read of the asset for you to use as needed.

A **mediaId** is the unique identifier FastPix assigns to every uploaded asset. You use the `mediaId` to read, update, or delete the asset and its `metadata`.

\


**Example:**

```json
"metadata": { 
  "category": "fitness", 
  "uploader_id": "user_9281" 
} 
```

\


### Why metadata matters

Adding `metadata` lets you:

* Organize videos by language, category, or campaign
* Link content to users, events, or content series
* Drive automation (for example, trigger AI moderation)
* Build internal tools and dashboards
* Power search and filtering in your UI
* Track publication, ownership, or licensing state

Without `metadata`, your video is a file with a URL. With `metadata`, it is a structured asset you can query and act on.

\


### Schema rules

To keep `metadata` predictable:

* Must be a **flat object**
* Max: **10 key-value pairs**
* Keys: **Strings only** (lowercase recommended)
* Values: **Strings** or **numbers**
* No nested objects or arrays

\


## Add metadata to on-demand videos

You can attach `metadata` at upload time through the API or through the FastPix dashboard. Use the API path for programmatic ingestion; use the dashboard for one-off uploads.

\


### Attach metadata on upload

Include a `metadata` object in the upload request body. An **accessPolicy** of `public` or `private` controls whether the resulting `playbackId` streams openly or requires a signed URL.

**`Request`**

```json Request
{ 
  "inputs": [ 
    { 
      "type": "video", 
      "url": "https://static.fastpix.com/sample.mp4" 
    } 
  ], 
  "metadata": { 
    "project": "app_launch", 
    "category": "yoga" 
  }, 
  "accessPolicy": "public", 
  "maxResolution": "1080p",
  "mediaQuality": "standard" 
} 
```

\


### Add metadata from the dashboard

You can add metadata to your media during the upload process using the FastPix dashboard.

#### Select your media settings

After uploading your video, the **Media Settings** panel opens. Under **Custom settings**, add your metadata as key-value pairs in the JSON configuration. For example:

```json
{
  "pushMediaSettings": {
    "metadata": {
      "key1": "value1"
    }
  }
}
```

Configure any other settings as needed, then click **Continue**.

\


#### Review metadata and start the upload

The **Metadata** panel displays a preview of your video along with auto-populated fields such as media title, duration, and aspect ratio. Optionally, edit the **Media title**, **Creator ID**, or **Third party ID**. When ready, click **Start upload all media**.

\


## Update metadata after upload

Send a `PATCH` request to the media endpoint to replace the `metadata` object on an existing asset.

\


**`PATCH`**

```Text PATCH
https://api.fastpix.com/v1/on-demand/{mediaId}
```

\


**Example**:

**`Request`**

```json Request
{ 
  "metadata": { 
    "language": "es", 
    "reviewed": "true" 
  } 
} 
```

\


**API reference**

For parameters, request schema, and response codes, see the [Update Media by ID API reference](/video-on-demand-api/manage-videos/updated-media).

\


**Full overwrite only** include every key you want to retain. Partial updates are not supported; any key omitted from the request is removed from the asset.

\


**Example use cases**

| Use case            | Metadata example                                     |
| ------------------- | ---------------------------------------------------- |
| Categorization      | `"genre": "sports", "language": "en"`                |
| UGC moderation      | `"uploaded_by": "user_123", "nsfw_checked": "false"` |
| Campaign tracking   | `"campaign": "launch_q3", "team": "marketing"`       |
| Workflow automation | `"transcription_required": "true"`                   |

\


#### Frequently asked questions

FastPix accepts up to 10 key-value pairs per asset. Keys must be strings, and values must be strings or numbers. Nested objects and arrays are rejected.

No. The `PATCH /on-demand/{mediaId}` endpoint replaces the full `metadata` object. Read the current asset, merge the fields you want to change in your application, then send the complete object back.

FastPix stores `metadata` and returns it on every asset read, but does not index it server-side for search. Use your own database or search layer to index `metadata` values if you need query-time filtering across your library.

No. FastPix treats `metadata` as opaque storage — it does not alter transcoding, `playbackId` behavior, or delivery based on its contents. Personalization and routing logic stay in your application.

\


## What's next?

* [Upload videos from URL](/upload-videos/upload-videos-from-a-url)
* [Update Media by ID API reference](/video-on-demand-api/manage-videos/updated-media)
* [Set up webhooks](/webhooks/set-up-webhooks)