LiveBroadcasts: cuepoint

Inserts a cuepoint into a live broadcast. The cuepoint might trigger an ad break.

Note: This method replaces the liveCuepoints.insert method, which required requests to be authorized by an account associated with a YouTube Content Owner. This method does not have the same authorization requirement.

Request

HTTP request

POST https://www.googleapis.com/youtube/v3/liveBroadcasts/cuepoint

Authorization

This request requires authorization with at least one of the following scopes. To read more about authentication and authorization, see Implementing OAuth 2.0 authentication.

Parameters

The following table lists the parameters that this query supports. All of the parameters listed are query parameters.

Parameters
Required parameters
id string
The id parameter identifies the broadcast into which the cuepoint is being inserted. The broadcast must be actively streaming when inserting the cuepoint.
Optional parameters
onBehalfOfContentOwner string
This parameter can only be used in a properly authorized request.
Note: This parameter is intended exclusively for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and perform actions on behalf of the channel specified in the parameter value, without having to provide different authentication credentials for each separate channel. The account that the user authenticates with must be linked to the specified YouTube content owner.
The onBehalfOfContentOwner parameter indicates that the request's authorization credentials identify a YouTube user who is acting on behalf of the YouTube Content Owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels.
onBehalfOfContentOwnerChannel string
This parameter can only be used in a properly authorized request.
Note: This parameter is intended exclusively for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and perform actions on behalf of the channel specified in the parameter value, without having to provide authentication credentials for each separate channel.
The onBehalfOfContentOwnerChannel parameter specifies the YouTube channel ID of the channel associated with the broadcast into which the cuepoint is being inserted. This parameter is required when a request specifies a value for the onBehalfOfContentOwner parameter, and it can only be used in conjunction with that parameter. The following requirements also apply:
  • The request must be authorized with a user account linked to the content owner that the onBehalfOfContentOwner parameter specifies.
  • The channel that the onBehalfOfContentOwnerChannel parameter value specifies must be linked to the content owner that the onBehalfOfContentOwner parameter specifies.

Request body

Provide a cuepoint resource in the request body. The following JSON structure shows the format of a cuepoint resource:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
 In the request body, the cueType field is required and must be set to cueTypeAd. You can also set values for these properties:
  • durationSecs
  • insertionOffsetTimeMs (must not be set if walltimeMs is set)
  • walltimeMs (must not be set if insertionOffsetTimeMs is set)

Properties

The following table defines the properties that appear in this resource:

Properties
id string
A value that YouTube assigns to uniquely identify the cuepoint. Note that this value is different from the required id parameter, which identifies the broadcast. This value can be omitted when sending a request to insert a cuepoint. The value will be populated in the API response.
insertionOffsetTimeMs long
The property value identifies a time offset, in milliseconds, when the cuepoint should be inserted. The value is measured from the beginning of the monitor stream, and its default value is 0, which indicates that the cuepoint should be inserted as soon as possible. You should not specify a value for this parameter if your broadcast does not have a monitor stream.

Though measured in milliseconds, the value is actually an approximation, and YouTube will insert the cuepoint as closely as possible to that time.

Non-zero values for this field are supported only if the broadcast stream is delayed. If your broadcast stream is not delayed, then 0 is the only valid value. For more details, see Getting started.

Note: If your broadcast had a testing phase, the offset is measured from the time that the testing phase began.

The API returns an error if a request tries to insert a cuepoint that specifies a value for this property and for the walltimeMs property.
walltimeMs integer
The property value specifies the wall clock time at which the cuepoint should be inserted. The value is an integer that represents an epoch timestamp (in milliseconds).

The API returns an error if a request tries to insert a cuepoint that specifies a value for this property and for the insertionOffsetTimeMs property.
durationSecs unsigned integer
The cuepoint's duration, in seconds. The value must be a positive integer. The default value is 30.
cueType string
The cuepoint's type. The property value must be set to cueTypeAd.

Response

If successful, this method returns the inserted cuepoint resource in the response body.

Errors

The following table identifies error messages that the API could return in response to a call to this method. For more details, see YouTube Live Streaming API - Errors.

Try it!

Use the APIs Explorer to call this API and see the API request and response.