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)
• 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)

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:

1
"metadata": { 
2
  "category": "fitness", 
3
  "uploader_id": "user_9281" 
4
} 

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.

1
{ 
2
  "inputs": [ 
3
    { 
4
      "type": "video", 
5
      "url": "https://static.fastpix.com/sample.mp4" 
6
    } 
7
  ], 
8
  "metadata": { 
9
    "project": "app_launch", 
10
    "category": "yoga" 
11
  }, 
12
  "accessPolicy": "public", 
13
  "maxResolution": "1080p",
14
  "mediaQuality": "standard" 
15
} 

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:

1
{
2
  "pushMediaSettings": {
3
    "metadata": {
4
      "key1": "value1"
5
    }
6
  }
7
}

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.

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

Example:

1
{ 
2
  "metadata": { 
3
    "language": "es", 
4
    "reviewed": "true" 
5
  } 
6
} 

API reference

For parameters, request schema, and response codes, see the Update Media by ID API reference.

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

Frequently asked questions

How many key-value pairs can I store in metadata?

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.

Can I do a partial update to metadata?

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.

Is metadata searchable or indexed by FastPix?

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.

Does FastPix use metadata to personalize playback or encoding?

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
• Update Media by ID API reference
• Set up webhooks