Use Asset Labels

  • The YouTube Content ID API, exclusive to YouTube content partners, offers a way to manage assets using custom categories called asset labels, which you can utilize to organize your asset library.

  • Asset labels can be created directly through the assetLabels.insert method or implicitly by updating an asset's labels via the assets.update method, and you can retrieve a complete list of them by calling the assetLabels.list method.

  • When updating asset labels with assets.update, the previous label list is entirely replaced, necessitating the prior use of assets.list to retain existing labels if needed, and labels can be applied to multiple assets, or a single asset can have multiple labels associated to it.

  • You can perform searches for assets associated with a specific label or a set of labels by using the assetSearch.list method, with options to find assets matching all or at least one of the specified labels.

Note: The YouTube Content ID API is intended for use by YouTube content partners and is not accessible to all developers or to all YouTube users. If you do not see the YouTube Content ID API as one of the services listed in the Google API Console, see the YouTube Help Center to learn more about the YouTube Partner Program.

Asset labels help you organize assets into custom categories, making it easier to organize your asset library. You can search for assets based on their labels, which can also simplify use cases that require you to update specific groups of assets.

This guide explains how to use the YouTube Content ID API to perform a number of common functions associated with labels. Several sections in this guide contain examples that link to and populate the Google APIs Explorer, enabling you to test each query.

Create asset labels

The API supports two ways to create asset labels:

  • Call the assetLabels.insert method. The body of the request is an assetLabel resource in which the labelName property specifies the unique name of the new label. The API returns a 409 (Conflict) HTTP response code if a label with the same name already exists.

    The query below calls the assetLabels.insert method to create a new label named Explorer Test. The body of the sample request is:

    {
  "labelName": "Explorer Test"
}

    The request does not set any query parameters. However, if your Google Account is associated with multiple content owner accounts, you must also set a value for the onBehalfOfContentOwner parameter.

    [no parameters set]

  • Call the assets.update method to update the labels for an asset. In the request, set the asset resource's label[] property to a list of labels associated with the asset. The API will automatically create new asset labels for any labels in the list that has not previously been explicitly created as assetLabel resources.

List a content owner's asset labels

To retrieve a list of a content owner's asset labels, call the assetLabels.list method.

  • By default, the API returns all asset labels for the content owner.
  • If you set a value for the labelPrefix query parameter, the API only returns the content owner's asset labels that begin with the specified string.

The following query calls the assetLabels.list method to retrieve all of the labels for a content owner. Note, however, that if your Google Account is associated with multiple content owner accounts, you must set a value for the onBehalfOfContentOwner parameter or the request will return a 400 (Bad Request) error.

[no parameters set]

The query below calls the same method but sets the labelPrefix parameter's value to news. As a result, the only labels that the API returns are those that begin with that string.

labelPrefix=news

Update an asset's labels

You can update an asset's labels by setting the value of the label[] property when calling the assets.update method. When you update an asset, its previous list of labels is removed and replaced with the list sent in the API request. As such, if you want to keep the previous list of labels, you should use the assets.list method to retrieve the original list of labels and then modify the label[] property's value. If the property value is empty, the API will remove the labels that had previously been associated with the asset.

You can associate the same label with multiple assets and also assign multiple labels with the same asset. Labels may contain spaces, meaning an individual label can be more than one word long. Prohibited characters are angled brackets, commas, colons, and vertical pipe characters (|). Each label must be at least two bytes long and may not be longer than 30 bytes. Each content owner can add up to 30 labels for an asset; the maximum total length for all labels for a given asset is 500 bytes.

Search for assets by label

To retrieve a list of assets associated with a label or group of labels, call the assetSearch.list method, using the labels query parameter to specify a comma-separated list of asset labels.

  • By default, the API will return a list of assets that have all of the specified asset labels.
  • If your API request sets the includeAnyProvidedLabel parameter to true, the API will return any asset that matches at least one of the specified labels.