Note: Complying with the YouTube Developer Policies provides guidance and examples to help you ensure that your API clients follow specific portions of the YouTube API Services Terms and Policies (API TOS). The guide offers insight into how YouTube enforces certain aspects of the API TOS, but it does not replace any existing documents.
This document defines minimum functional requirements for API clients that implement or provide access to specific features of YouTube API services ("API Clients").
These requirements and guidelines ensure that API clients provide a consistent user experience that protects the interests of YouTube users, content owners, and advertisers. These rules are an integral part of the YouTube API Terms of Service and must be followed in the development and implementation of any API Clients.
You should expect the requirements in this document to change so that we can ensure better user experiences with existing YouTube features. They will also change in response to new and updated YouTube features. At times, such changes may require you to update your API Clients to address new requirements. The Terms of Service revision history will document any changes, so please check that document frequently, or subscribe to its RSS feed, to ensure that you can quickly learn about changes that may affect your API Clients.
In addition to the requirements in this document, we highly recommend that you follow best practices described in the YouTube API Services Policies and discussed elsewhere in YouTube API services' documentation. Even when not strictly required, these practices help your API Clients to recover more quickly from errors and to optimize their quota usage if they use YouTube API services that allocate quota. At the same time, these practices help to ensure the health of the YouTube ecosystem and, above all, to provide the best experience possible to users of your API Clients and of YouTube Applications.
YouTube embedded player and video playback
The requirements in this section relate specifically to embedded YouTube players. The YouTube API Services Policies also includes several policies relevant to API Clients that play YouTube audiovisual content.
Embedded YouTube Player size
Embedded players must have a viewport that is at least 200px by 200px. If the player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.
Autoplay and scripted playbacks
This section covers automatic playbacks. It applies to YouTube embedded players that either use the autoplay player parameter or programmatically initiate automatic playback using the YouTube IFrame Player API service, the YouTube Android Player API service, or another YouTube API service.
-
Embedded players that automatically play a video should initiate playback immediately when the page loads or as soon as the embedded player is fully visible. However, an API Client must not initiate an automatic playback until the player is visible and more than half of the player is visible on the page or screen.
-
A page or screen must not have more than one YouTube player that automatically plays content simultaneously.
-
Any YouTube thumbnail that initiates a playback must be at least 120 pixels wide and 70 pixels tall.
YouTube Player attributes
Attributes and parameters of the YouTube player – including, for example, the appearance of YouTube branding in the player – are specified in YouTube API documentation and specifications (https://developers.google.com/youtube). You must not make changes to the YouTube player that are not explicitly described by the API documentation.
Overlays and frames
You must not display overlays, frames, or other visual elements in front of any part of a YouTube embedded player, including player controls. Similarly, you must not use overlays, frames or other visual elements to obscure any part of an embedded player, including player controls.
Mouseovers
You must not use mouseovers or touch events on a YouTube player to initiate any action on the user's behalf, such as opening a window or subscribing to a channel.
Uploading videos
If API Clients allow users to upload content to multiple platforms, users should be able to select and deselect the platforms to which they want to upload their videos.
Data requirements
API clients that enable users to upload videos to YouTube must enable users to set the values in the following list. Any properties that are not listed are optional.
| Name | Description | |
|---|---|---|
| Resource properties | ||
snippet.title |
Required. The video's title. YouTube returns an error if the value exceeds 100 characters. YouTube supports all valid UTF-8 characters except < and >.
| |
snippet.description |
Required. The video's description. YouTube returns an error if the value exceeds 5000 bytes. YouTube supports all valid UTF-8 characters except < and >. |
|
status.privacyStatus |
Required. The video's privacy setting. Users must be able to choose whether the uploaded video will be public, private, or unlisted. | |
| Request parameters | ||
onBehalfOfContentOwnerChannel |
Conditionally required. If the request's authorization credentials identify a content owner and the onBehalfOfContentOwner parameter is set, the API user must also be able to specify the YouTube channel to which the video is being uploaded. |
|
Displaying comments
| Name | Description | |
|---|---|---|
| Resource properties | ||
snippet.textDisplay |
Required. The comment's text. The API client must either (a) display the full text of a comment or comment reply, or (b) truncate the text and provide a way for the viewer to easily access the full text from the truncated version. This requirement applies to all comments and comment replies, regardless of which type of resource the comments are associated with (videos, channels, etc.). Note that the commentThread resource's snippet.topLevelComment property value is a comment resource and the replies.comments[] property is a list of comment resources. As such, this requirement also applies to the snippet.topLevelComment.snippet.textDisplay and replies.comments[].snippet.textDisplay properties. |
|
snippet.title( channel) |
Required (suggestion). The channel's title.
|
|
snippet.title( video) |
Conditionally required (suggestion). The video's title. This value must be displayed if the comment pertains to a video. | |
snippet.moderationStatus |
Conditionally required. If the moderationStatus parameter value in the API request is heldForReview or likelySpam, the display must clearly identify that status using the property value, similar language (e.g. "This comment is being held for review"), a header (e.g. "Held for review"), or other unambiguous language. The commentThreads.list method supports the ability to retrieve comments based on their moderation status. |
|
Adding comments
| Name | Description | |
|---|---|---|
| Resource properties | ||
snippet.title( channel) |
Required. The channel's title.
|
|
snippet.title( video) |
Required. If the user is adding a comment about a video, the API client must display the video's title. | |
| Other requirements | ||
Comment author's channel name |
Required. The API client must clearly identify the YouTube user account to which the comment will be attributed. If the request's authorization credentials identify a content owner and the onBehalfOfContentOwner parameter is set, the API user must also be able to specify the YouTube channel to which the comment will be attributed. |
|
Adding comment replies
| Name | Description | |
|---|---|---|
| Resource properties | ||
snippet.textDisplay |
Required. The comment's text. The API client must display the text of the comment that the user is replying to in accordance with the rules defined in the Displaying comments section of this document. | |
snippet.title( channel) |
Required. The channel's title.
|
|
snippet.title( video) |
Required. If the user is replying to a comment about a video, the API client must display the video's title. | |
| Other requirements | ||
Comment author's channel name |
Required. The API client must clearly identify the YouTube user account to which the comment reply will be attributed. If the request's authorization credentials identify a content owner and the onBehalfOfContentOwner parameter is set, the API user must also be able to specify the YouTube channel to which the comment reply will be attributed. |
|
Editing or deleting comment replies
| Name | Description | |
|---|---|---|
| Resource properties | ||
snippet.textDisplay |
Required. The comment's text. The API client must display the text of the comment that the user is editing or deleting in accordance with the rules defined in the Displaying comments section of this document. | |
snippet.title( channel) |
Required. The channel's title.
|
|
snippet.title( video) |
Required. If the user is editing or deleting a comment about a video, the API client must display the video's title. | |
| Other requirements | ||
Comment author's channel name |
Required. The API client must clearly identify the YouTube user account to which the comment is attributed. | |
Banning a user from live chat (or removing a ban)
| Name | Description | |
|---|---|---|
| Resource properties | ||
snippet.title( channel) |
Required. The name of the YouTube channel that is being banned or unbanned. In addition, the name must link to the channel or the channel URL must also be displayed. | |
| Other requirements | ||
| Comment author's channel name | Required. The API client must clearly identify the YouTube user account being used to add or remove the ban. | |