YouTube API v2.0 – Uploading Videos

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information. Please use the YouTube Data API (v3) for new integrations and migrate applications still using the v2 API to the v3 API as well.

The YouTube Data API provides two methods for uploading videos to YouTube. A newly uploaded video will be included in a user's uploaded videos feed a few minutes after the upload completes and YouTube finishes processing the video. In addition, a newly uploaded video will typically be included in search results a couple of hours after the upload completes and YouTube finishes processing the video. However, this delay may be longer during periods of heavy API server loads.

  • Browser-based uploading allows you to accept video uploads from your users without having to handle, host or proxy the actual video files. You should choose a browser-based uploading process if you do not want to host or store the uploaded video files.

  • Direct uploading allows you to add videos that are in your video library to YouTube. You should choose a direct-upload implementation if you want to host or store videos uploaded through your site and also add those videos to YouTube. In a direct-uploading scenario, when a user uploads a video through your site, the video will be sent to your servers. Your application will subsequently send an API request to upload the video from your server to YouTube.

    The API also supports a direct, resumable uploading process, which can be restarted from the point of interruption if the connection between your application and YouTube is lost at any point during the uploading process.

In addition to choosing an uploading method, you must also choose the authentication scheme appropriate for your application. The following sections provide additional information about the video uploading process:

  1. Requirements for uploaded videos
  2. Setting access controls for a video
  3. Assigning developer tags
  4. Browser-based uploading
  5. Direct uploading
  6. Checking the status of an uploaded video

Requirements for uploaded videos

You must be either the copyright holder or the authorized representative of the copyright owner for all video files that you deliver to YouTube. Similarly, users who upload videos to YouTube from your site must be either the copyright holder or the authorized representative of the copyright owner for all videos that they upload.

Technical requirements

We encourage you and your users to provide the highest quality video possible. YouTube's recommended video specifications can be found online in YouTube's Help Center and we recommend that you convey these guidelines to your users.

In addition to these guidelines, please note that video files must be 64 GB or smaller. All users can upload videos up to 15 minutes long, and many users with a history of complying with the YouTube Community Guidelines can upload videos longer than that. You may compress API requests using gzip transfer-encoding. However, please note that the 64 GB size restriction still applies to the uncompressed video file.

Metadata requirements

Each uploaded video must have a title and must also be associated with a category. You can choose any of the following methods to set these values:

  • You can specify the title and category for an uploaded video using the <media:title> and <media:category> elements.

  • You can include the <yt:incomplete> element in the uploaded video's metadata. This element instructs YouTube to automatically generate certain metadata values if they are not otherwise specified. YouTube uses the following rules to generate metadata if the <yt:incomplete> element is included in the metadata for the uploaded video:

    • If the entry does not contain a <media:title> element, YouTube sets the video's filename as the video title. If you use browser-based uploading, the filename is passed in the file input field. If you use direct uploading, including resumable uploading, the filename is the value of the Slug HTTP request header.
    • If the entry does not contain a <media:keywords> element, YouTube sets the video's filename as the video's keyword tag.
    • If the entry does not contain a <media:category> element, YouTube sets the video's category to the category of the last video that the user uploaded. If no prior upload exists, YouTube sets the video's category to People.

    For example, the sample direct uploading request below would upload a video with the title summer_vacation.mp4 and keyword summer_vacation.mp4 in the Travel & Events category.

    POST /feeds/api/users/default/uploads HTTP/1.1
    Authorization: Bearer ACCESS_TOKEN
    GData-Version: 2
    X-GData-Key: key=adf15ee97731bca89da876c...a8dc
    Slug: summer_vacation.mp4
    Content-Type: multipart/related; boundary="f93dcbA3"
    Content-Length: 1941255
    Connection: close
    Content-Type: application/atom+xml; charset=UTF-8
    <?xml version="1.0"?>
    <entry xmlns=""
    Content-Type: video/mp4
    Content-Transfer-Encoding: binary
    <Binary File Data>
  • If you are uploading videos via the resumable uploading process, you can upload a video without any metadata whatsoever. See the Uploading a video without metadata section for details about this option for resumable uploads. In this case, YouTube will handle the absence of metadata as if the upload request consisted of an <entry> that only contained a <yt:incomplete> element.

You can only include the <yt:incomplete> element in a video entry at the time that you upload the video. When you retrieve a video entry for a video uploaded with incomplete metadata, the entry will contain the <yt:incomplete> element. If you choose to update the video, you must at least remove the <yt:incomplete> element from the entry before submitting your update request.

Note that videos uploaded with the <yt:incomplete> element will not be included in YouTube's search index, and therefore will not appear in search results, until their metadata has been updated. After the video's metadata is updated, and the <yt:incomplete> element is removed from the metadata, then the video will be eligible for inclusion in YouTube's search index.

Setting access controls for a video

When uploading (or updating) a video, you can specify access controls for that video. The table below defines the access controls that you can set for each video and lists the permissions that you can set for each control. The default setting for each control is marked with an asterisk.

Control Permissions Definition
rate allowed*
This control indicates whether users can rate the video.
comment allowed*
This control indicates whether users can add comments about the video. If you moderate comments, then you must approve new comments before they will be visible to other users.
commentVote allowed*
This setting indicates whether users can rate comments about the video.
list allowed*
This setting indicates whether a video can be listed in YouTube search results or displayed in any other way unless the user has a URL that links directly to the video. The permission for this setting will be denied if the video is either unlisted or private. If you set the value to denied for a public video, then that video will become an unlisted video.
embed allowed*
This setting indicates whether users can embed the video on third-party websites.
syndicate allowed*
This setting indicates whether YouTube can show the video on non-web platforms, such as mobile phones and televisions.

To set access controls for a video, include one <yt:accessControl> tag for each control that you want to set as shown in the following example:

  <yt:accessControl action='rate' permission='allowed'/>

If you do not specify access control settings when you upload (or update) a video, YouTube will apply the default access controls for that video. If you only specify some access controls, then default settings will be applied for the unspecified controls. Finally, the API will return an error if you specify multiple permissions for the same access control, with the exception of the special use case for comments described below.

Note: If a user has uploaded content, such as a music video, that is owned by another user, then the actual content owner may override the access control settings that the uploader provided. See the <yt:accessControl> tag definition for a list of exceptions.

Assigning developer tags

When you upload a video, you can associate that video with one of YouTube's video categories. You can also associate the video with additional keywords, or developer tags, that you use to identify the video. By using developer tags, you can identify all of the videos uploaded through your website or even through specific areas of your website. YouTube will not display developer tags to YouTube users; however, you can retrieve or update videos that match a specific developer tag.

Note: You can only associate developer tags with a video at the time that the video is uploaded. In addition, developer tags that are assigned when a video is uploaded cannot be altered thereafter.

To associate developer tags with a video, include one <media:category> tag in your Upload API request for each developer tag. Set the value of the scheme attribute to and the tag value to the keyword you want to associate with the video. When choosing values to use for developer tags, remember that developer tag searches are not case-sensitive. In addition, note the following restrictions:

  • Each developer tag must be at least three bytes long.
  • Each developer tag cannot be longer than 25 bytes.
  • The total length of all developer tags cannot exceed 240 bytes.

The following XML shows a sample developer tag as it would appear in an Upload API request. (You would need to replace the string TagName with the actual keyword or label you wanted to associate with the video.)


In an API response, developer tags are specified in both <category> and <media:category> tags.

Note: Each developer tag that you assign will be associated with the developer key in your request. To search for videos matching that developer tag, your application would need to specify the same developer key in the search request.

Searching for videos that match a developer tag

To search for videos associated with a specific developer tag, send an API search request that specifies the category scheme and the developer tag that videos must match. Developer tag searches are not case-sensitive. The URLs below demonstrate how you would modify the standard API URL to match a developer tag. (You would need to replace the string TagName at the end of the URL with the name of your developer tag.)

Standard URL:

Retrieving videos associated with a developer tag:

Note: When you search for videos that match a developer tag, your request must specify the same developer key that you used to assign that developer tag.

pagination links

« Previous
Searching for Playlists
Next »
Browser-based Uploading