Note:Complying with the YouTube Developer Policiesprovides guidance and examples to help you ensure that your API clients follow specific portions of the YouTube API ServicesTermsandPolicies(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 theYouTube API Terms of Serviceand 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. TheTerms of Service revision historywill document any changes, so please check that document frequently, or subscribe to itsRSS 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 theYouTube API Services Policiesand 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 theautoplayplayer 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 /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 enableusersto 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'sprivacy 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 theonBehalfOfContentOwnerparameter 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 commentThreadresource'ssnippet.topLevelCommentproperty value is acommentresource and thereplies ments[]property is a list ofcommentresources. As such, this requirement also applies to thesnippet.topLevelComment.snippet.textDisplayandreplies ments[].snippet.textDisplayproperties. |
|
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 themoderationStatusparameter value in the API request isheldForRevieworlikelySpam,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. ThecommentThreads.listmethod 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 theonBehalfOfContentOwnerparameter 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 theDisplaying commentssection 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 theonBehalfOfContentOwnerparameter 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 theDisplaying commentssection 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. | |