YouTube API v2.0 – Resumable Uploads

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.

This section explains how to upload videos using YouTube's direct, resumable uploading process. Direct uploading lets you add videos to YouTube from your video library. In addition, resumable uploads 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.

You should choose a direct-upload implementation if either of the following conditions is true:

You have a collection of videos that want to upload to YouTube.

You want to host or store videos uploaded through your site and also add those videos to YouTube.

You want to upload videos from a device with a low-bandwidth or unstable Internet connection, such as a mobile device.

If you implement direct uploading for a website, then when a user uploads a video to 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.

Step 1 - Uploading video metadata

To begin a resumable upload, send a POST request that contains the video filename and the metadata for the video to the following URL. The authentication token that you submit with the request needs to identify the currently logged-in user.
Note that this URL is almost the same one that you would use for non-resumable direct uploading, with the difference being the addition of the resumable path prefix in the URL.

CONTENT_LENGTH - This value contains the length, in bytes, of the entire body of the POST request.

VIDEO_FILENAME - This value contains the file name of the source video that you are uploading.

API_XML_Request - This value contains information about the uploaded video file in the form of an Atom XML entry. The example below shows a sample XML request. The XML tags used in the entry are defined in the Reference Guide.

The following example shows a POST request that has all of these values
populated with the exception of the access (authentication) token:

Uploading a video without metadata

When using the resumable uploading process, you can upload a video without specifying any metadata at all. In such cases, YouTube will handle the request as if it contained an entry that only included a <yt:incomplete> element. YouTube would then generate certain metadata values for the video as discussed in the metadata requirements for uploaded videos.

A resumable upload request that does not specify any metadata differs from the sample resumable upload request shown above in three ways:

The Content-Length HTTP request header value must be 0.

The Content-Type HTTP request header must be omitted from the request.

The Atom XML entry is omitted from the request.

The example below shows an API request to upload a video without metadata using the resumable uploading process:

Step 2 - Extracting the upload URL from the API response

When you submit an API request to upload video metadata, the API response will contain a Location header, which identifies the URL that you will use to upload the actual video file. You need to extract this URL and use it to upload the video file.

The example below shows a sample API response to a request to upload video metadata for a resumable upload:

Step 3 - Uploading the video file

After extracting the upload URL from the API response, you need to upload the actual video file content. You will upload the video content to the URL extracted in step 2. The example below demonstrates the format of the video upload request. Note that you do not need to provide any authentication headers in this step.

Step 4 - Completing the upload process

When you submit a request to upload the video content for a resumable upload, one of two scenarios could occur:

If the upload completes, then the API returns a response indicating whether the upload succeeded or failed.

For a successful upload, the API returns an Atom entry that contains information about the uploaded video. The entry has the same format as an entry in a user's uploaded videos feed, and the response may contain properly escaped HTML tags. The Checking the status of an uploaded video section explains how to check the status of the uploaded video.

For an unsuccessful upload, the response contains an error response that helps to explain the cause of the upload failure.

If the upload fails because the connection between the YouTube server and your application is lost, then your application will not receive an API response. In this case, you may be able to resume the upload from the point of the interruption. The following steps explain how to resume a video upload:

Checking the status of a resumable upload

To query the status of an interrupted resumable upload, send a PUT request to the upload URL that you retrieved in step 2 and also used in step 3. In your request, you need to set the Content-Range header value to bytes */* as shown in the following example:

If the upload URL refers to an upload that completed, regardless of whether the upload succeeded or failed, the API will return the same response that it sent when the upload originally completed. As discussed above, if the upload succeeded, the response will contain an Atom entry. If the upload failed, the response will contain the original error response.

However, if the upload was interrupted by a lost connection, the API will return a 308 HTTP response code (Resume Incomplete). The sample response below shows the format of an API response for an upload that can still be completed:

In the response, the range header indicates how many bytes from the video file have already been successfully uploaded to YouTube. The bytes are indexed from 0. Thus, the sample response above indicates that the first 409 bytes of the file were received. If nothing has been uploaded yet, the range header will be absent from the response.

Note: The API response for an upload that can still be completed may use the Location header to specify a new unique upload URI that your application should use to complete the upload. Your client should check the API response for an updated location and, if one is present, use it to upload the remaining data.

Resuming an upload

To resume the upload, you will send a new PUT request to the upload URL captured in step 2. The resumed upload request has the following format:

You must provide several values in the PUT request. Those values are highlighted in bold text in the example above. The following list explains how to populate each value:

upload_url – This value is the upload URL that you extracted in step 2.

video_content_type – This value specifies the MIME type of the uploaded video file. The MIME type can be a video media type, such as video/mpeg or video/mp4, or it can be application/octet-stream.

content_length – This value specifies the length, in bytes, of the entire body of the PUT request. If you are uploading the remainder of a video file, you can calculate this value by subtracting the first_byte from the total_content_length. (Both of these values are defined below.)

The Content-Range header specifies the part of the video file that you are uploading. The header specifies three values:

The first_byte specifies the 0-based numeric index of the byte number from which you are resuming the upload. This value will be one number higher than the second number in the range header retrieved in the previous step. In the previous example, the range header value was 0-408. The first byte in a subsequent resumed upload would be 409.

The last_byte specifies the 0-based numeric index of the last byte included in the binary file that you are uploading. Typically, this will be the last byte in the file. In step 3, the Content-Length header value was 124905. Thus, the last byte in the file would be number 124904.

The total_content_length specifies the total size of the video file in bytes. This value is the same as the Content-Length submitted in the original upload request.

Binary File Data – This value contains the binary code for the portion of the video file that you are uploading.

Note: You cannot upload a noncontinuous block of the binary file. If you try to upload a noncontinuous block, none of the remaining binary content will be uploaded. As such, the first byte in the upload request must be the next byte after the last byte successfully uploaded to YouTube as identified in the range header of the 308 HTTP response. Thus, if the last byte in the range header is 408, the first byte in the request to resume the upload must be byte 409 (using a 0-based index). If you try to resume the upload from byte 408 or lower (overlapping bytes) or byte 410 or higher (skipping bytes), none of the binary content will be uploaded.