REST Resource: references

  • A Reference represents the actual content of an asset and is used by YouTube to generate claims for asset owners by comparing it to newly uploaded videos.

  • References have various attributes, including status, length, content type, and origination, and they can be marked as urgent for prioritized Content ID processing.

  • The ExcludedInterval feature allows specifying time windows within a reference that will be ignored during the match process, defined by low and high time markers.

  • References can be managed through various methods, such as retrieving, creating, updating, and patching, each serving a specific function in managing reference content.

  • The reference can be associated to an existing video, and in this case will have the corresponding videoId and claimId values.

Resource: Reference

A reference represents the actual content of an asset. YouTube compares newly uploaded videos to a library of references for the purpose of automatically generating claims for the asset's owner(s).

JSON representation 
{
  "kind": string,
  "status": string,
  "statusReason": string,
  "length": number,
  "hashCode": string,
  "urgent": boolean,
  "fpDirect": boolean,
  "contentType": string,
  "audioswapEnabled": boolean,
  "ignoreFpMatch": boolean,
  "origination": {
    object (Origination)
  },
  "excludedIntervals": [
    {
      object (ExcludedInterval)
    }
  ],
  "id": string,
  "assetId": string,
  "duplicateLeader": string,
  "claimId": string,
  "videoId": string
}
Fields
kind

string

The type of the API resource. For reference resources, the value is youtubePartner#reference.
status

string

The reference's status. Acceptable values are:

  • activating - The reference is pending activation.
  • active - The reference is active and actively matching.
  • checking - The reference is being compared to existing references to identify reference conflicts.
  • checking_quota - The reference is awaiting quota verification.
  • computing_fingerprint - The reference's fingerprint is being computed.
  • deactivating - The reference is in the process of being deactivated.
  • deleted - The reference has been deleted.
  • inactive - The reference is inactive.
  • live_streaming_processing - The reference is being processed from a live video stream.
statusReason

string

An explanation of how a reference entered its current state. This value is only present if the reference's status is either inactive or deleted. Acceptable values include:

  • ACTIVATION_QUOTA_EXCEEDED - Activation quota was exceeded.
  • ALMOST_ENTIRELY_EXCLUDED - The reference is almost entirely excluded.
  • ASSET_MERGE_FAILED - Reference became inactive due to an asset merge failure.
  • BATCH - Processing failed during batch ingestion.
  • BULK_UPDATER - Status was updated by bulk updater.
  • CLAIM_DISABLED_FOR_MATCHING - Matching was disabled on the claim.
  • CLOSED_BY_OWNER - Closed by the asset owner.
  • DUPLICATE_FOR_OWNERS - Reference duplicates another reference for the same owner.
  • ERROR_DURING_ACTIVATION - Error occurred during activation.
  • INSUFFICIENT_LENGTH - Reference length is insufficient for fingerprinting.
  • NON_PERFORMING - Reference was deactivated due to non-performance.
  • PROCESSING_FAILED - Reference ingestion or processing failed.
  • PROCESSING_QUOTA_EXCEEDED - Processing quota was exceeded.
  • REFERENCE_WAS_REMOVED - Source reference file was removed.
  • USER_WAS_REMOVED - User account was removed.
  • VIDEO_WAS_REMOVED - Source video was removed.
  • VIDEO_WIPED_OUT - Video was deleted or wiped out.
length

number

The length of the reference in seconds.
hashCode

string

The MD5 hashcode of the reference content. Deprecated! This is no longer populated.
urgent

boolean

Set this value to true to indicate that YouTube should prioritize Content ID processing for a video file. YouTube processes urgent video files before other files that are not marked as urgent. This setting is primarily used for videos of live events or other videos that require time-sensitive processing. The sooner YouTube completes Content ID processing for a video, the sooner YouTube can match user-uploaded videos to that video.

Marking all of your files as urgent could delay processing for those files.
fpDirect

boolean

When uploading a reference, set this value to true to indicate that the reference is a pre-generated fingerprint.
contentType

string

The type of content that the reference represents.

Acceptable values are:

  • audio
  • audiovisual
  • video
audioswapEnabled

boolean

Set this field's value to true to indicate that the reference content should be included in YouTube's AudioSwap program.
ignoreFpMatch

boolean

Set this value to true to indicate that the reference should not be used to generate claims. This field is only used on AudioSwap references.
origination

object (Origination)

The origination object contains information that describes the reference source.
excludedIntervals[]

object (ExcludedInterval)

The list of time intervals from this reference that will be ignored during the match process.
id

string

A value that YouTube assigns and uses to uniquely identify a reference.
assetId

string

The ID that uniquely identifies the asset that the reference is associated with.
duplicateLeader

string

The ID that uniquely identifies the reference that this reference duplicates. This field is only present if the reference's status is inactive with reason REASON_DUPLICATE_FOR_OWNERS.
claimId

string

This field is present if the reference was created by associating an asset with an existing YouTube video that was uploaded to a YouTube channel linked to your CMS account. In that case, this field contains the ID of the claim representing the resulting association between the asset and the video.
videoId

string

This field is present if the reference was created by associating an asset with an existing YouTube video that was uploaded to a YouTube channel linked to your CMS account. In that case, this field contains the ID of the source video.

ExcludedInterval

Defines a time window within the reference that will be ignored during the match process.

JSON representation 
{
  "low": number,
  "high": number,
  "origin": string,
  "timeCreated": string
}
Fields
low

number

The start (inclusive) time in seconds of the time window. The value can be any value between 0 and high. Every interval must specify a value for this field.
high

number

The end (inclusive) time in seconds of the time window. The value can be any value greater than low. If high is greater than the length of the reference, the interval between low and the end of the reference will be excluded. Every interval must specify a value for this field.
origin

string

The source of the request to exclude the interval from Content ID matching. Acceptable values are:

  • content_id_api - The excluded interval was created manually using the Content ID API.
  • content_manager - The excluded interval was created in YouTube Studio or Content Manager.
  • ingestion - The excluded interval was specified in an uploaded content feed.
  • invalid_segment - The segment in the reference is invalid for matching.
  • permanent_exclusion - The segment was identified by YouTube as invalid for matching.
  • reference_conflict - The excluded interval originated from a reference conflict.
  • unknown - The exclusion source is unknown.
timeCreated

string

The date and time that the exclusion was created. The value is specified in RFC 3339 (YYYY-MM-DDThh:mm:ss.000Z) format.

Methods

get

 Retrieves information about the specified reference.

insert

Creates a reference in one of the following ways:

  • If your request is uploading a reference file, YouTube creates the reference from the provided content.

list

 Retrieves a list of references by ID or the list of references for the specified asset.

patch

 Patches a reference.

update

 Updates a reference.