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 .

    Scope
    https://www.googleapis.com/auth/youtube
    https://www.googleapis.com/auth/youtube.force-ssl
    https://www.googleapis.com/auth/youtubepartner

    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 .

    Error type Error detail Description
    insufficientPermissions (403)
    		insufficientLivePermissions The request is not authorized to insert a cuepoint in the live broadcast.
    insufficientPermissions (403)
    		liveStreamingNotEnabled The user that authorized the request is not enabled to stream live video on YouTube. The user can find more information at Get started with live streaming and Feature eligibility .
    rateLimitExceeded (403)
    		userRequestsExceedRateLimit The user has sent too many requests in a given timeframe.
    required (400)
    		idRequired The required id parameter must identify the broadcast in which you want to insert a cuepoint.
    required (400)
    		cueTypeRequired The required cueType field must be specified in the API request body.
    notFound (404)
    		liveBroadcastNotFound The broadcast specified by the id parameter does not exist.
    invalidValue (400)
    		conflictingTimeFields Only one of insertionOffsetTimeMs and walltimeMs may be specified. Setting both values causes an error. If you do not set either value, YouTube will use the default insertionOffsetTimeMs time ( 0 ), which means that the cuepoint will be inserted as soon as possible.
    invalidValue (400)
    		invalidInsertionOffsetTimeMs The cuepoint resource specified an invalid value for the insertionOffsetTimeMs property. The value must be 0 or a positive integer.
    invalidValue (400)
    		invalidWalltimeMs The cuepoint resource specified an invalid value for the walltimeMs property. The value must be an integer that represents an epoch timestamp (in milliseconds).
    backendError (5xx)
    		serviceUnavailable The service is unavailable. Try your request again after a few minutes.

    Try it!

    Use the APIs Explorer to call this API and see the API request and response.
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: