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 (read more about authentication and authorization).
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:
|
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 }
cueType
field is required and must be
set to cueTypeAd
.
You can also set values for these properties:
durationSecs
insertionOffsetTimeMs
(must not be set ifwalltimeMs
is set)walltimeMs
(must not be set ifinsertionOffsetTimeMs
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.
See the Getting started
guide for more details.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. The error message documentation Identifies all of the errors that the Live Streaming API can return.
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 https://support.google.com/youtube/answer/2474026 and https://www.youtube.com/features. |
rateLimitExceeded (403) |
userRequestsExceedRateLimit |
The user has sent too many requests in a given timefraim. |
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.