Add metadata to your videos

What is asset metadata?

Metadata provides additional descriptive information about your video assets. Mux currently supports three key optional metadata fields that help you organize and manage your video content across the API and dashboard:

• title: A descriptive name for your video content. We limit this to 512 code points.
• creator_id: A value you set to identify the creator or owner of the video. We limit this to 128 code points.
• external_id: Another value you set to reference this asset in your system, such as the video ID in your database. We limit this to 128 code points.

Here's an example of what a meta object might look like:

{
   "title": "Guide: Adding metadata to videos",
   "creator_id": "user_23456",
   "external_id": "cdef2345"
}

Once set on an asset, you'll find this metadata on assets across the Mux API and dashboard, including asset management, engagement and data.

Manage metadata through the Dashboard

We've deeply integrated asset metadata throughout the Mux dashboard:

• When uploading, we use your filename as the title - but you can change it at any time
• For live streams, you can set the default metadata for recordings on the stream details page
• When viewers watch your content, all metadata flows into Mux Data and the engagement dashboard - making it easy to find videos by title, or filter by creator id.

Manage metadata through the API

Create an asset with metadata

When creating an asset you can include your metadata in the body of the request.

Example request

// POST /video/v1/assets
{
    "input": "https://storage.googleapis.com/muxdemofiles/mux.mp4",
    "playback_policy": "public",
    "video_quality": "basic",
    "meta": {
        "title": "Mux demo video",
        "creator_id": "abcd1234",
        "external_id": "bcde2345"
    }
}

Need more help?

• Check out our getting started guide for a more thorough introduction to creating assets.
• Check out our Create an assetAPI for a list of all possible parameters.

Update the metadata on an asset

Once an asset has been created the metadata can be changed at any time. Make a request to update the asset and include your metadata in the request body.

Example request

// PATCH /video/v1/assets/{ASSET_ID}
{
    "meta": {
        "title": "Updated Mux demo video",
        "creator_id": "cdef3456",
        "external_id": "defg4567"
    }
}

Need more help?

• Check out our Update asset API referenceAPI for more details.

Directly upload a video with metadata

Direct uploads are a multi-step process, and metadata should be attached in the very first step. When creating your authenticated URL in that first step you can include your metadata alongside the rest of the asset settings in new_asset_settings.

Example Request

// POST /video/v1/uploads
{
    "new_asset_settings": {
        "playback_policy": "public",
        "video_quality": "basic",
        "meta": {
            "title": "Mux demo video",
            "creator_id": "abcd1234",
            "external_id": "bcde2345"
        }
    },
    "cors_origin": "*",
}

Need more help?

• Check out our direct upload guide for details on every step.

Set live stream metadata defaults for creating assets

Mux automatically creates a new asset each time you connect to a live stream. When creating or updating your live stream you can include metadata that gets automatically set on the generated assets in the request body, under new_asset_settings.

Example "Create Live Stream" request

// POST /video/v1/live-streams
{  
    "playback_policy": "public",
    "new_asset_settings": {  
        "playback_policy": "public",
    },  
    "meta": {  
        "title": "Mux demo live stream recording",  
        "creator_id": "abcd1234",  
        "external_id": "bcde2345"  
    }  
}

Need more help?

• Check out our "start live streaming" guide for a deeper walkthrough.