YouTube

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.

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.

This page contains the following sections:

  1. Step 1 - Uploading video metadata
  2. Step 2 - Extracting the upload URL from the API response
  3. Step 3 - Uploading the video file
  4. Step 4 - Completing the upload process

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.

http://uploads.gdata.youtube.com/resumable/feeds/api/users/default/uploads

The example below shows the format of an API request that uses the OAuth 2.0 authentication scheme for resumable uploading:

POST /resumable/feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY
Content-Length: CONTENT_LENGTH
Content-Type: application/atom+xml; charset=UTF-8
Slug: VIDEO_FILENAME

API_XML_request

Variables in the upload request

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

  • ACCESS_TOKEN - This value contains the authentication token for your request. The token will either be an OAuth 2.0 access token, an OAuth 1.0 access token, a ClientLogin token, an AuthSub single-use token, or an AuthSub session token.

  • DEVELOPER_KEY - This value uniquely identifies the application that is submitting the request to upload the video. Please visit http://code.google.com/apis/youtube/dashboard/ to get a developer key.

  • 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:

POST /resumable/feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=adf15ee97731bca89da876c...a8dc
Content-Length: 1941255
Slug: my_file.mp4
Content-Type: application/atom+xml; charset=UTF-8

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
  xmlns:media="http://search.yahoo.com/mrss/"
  xmlns:yt="http://gdata.youtube.com/schemas/2007">
  <media:group>
    <media:title type="plain">Bad Wedding Toast</media:title>
    <media:description type="plain">
      I gave a bad toast at my friend's wedding.
    </media:description>
    <media:category
      scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People
    </media:category>
    <media:keywords>toast, wedding</media:keywords>
  </media:group>
</entry>

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:

POST /resumable/feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=adf15ee97731bca89da876c...a8dc
Content-Length: 0
Slug: my_file.mp4

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:

HTTP/1.1 200 OK
Location: http://uploads.gdata.youtube.com/resumableupload/AF8GKF...0Glpk0Aw
Date: Fri, 04 Dec 2009 16:14:30 GMT
Pragma: no-cache
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 0
Content-Type: text/html

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.

PUT <upload_url> HTTP/1.1
Host: uploads.gdata.youtube.com
Content-Type: <video_content_type>
Content-Length: <content_length>

<Binary_file_data>

Variables in the upload request

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 URL that you extracted in step 2 from the Location header of the API response for the metadata upload request.

  • 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.

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

The following example shows a PUT request that has all of these values populated with the exception of the binary file data:

PUT /resumableupload/AF8GKF...0Glpk0Aw HTTP/1.1
Host: uploads.gdata.youtube.com
Content-Type: video/mpeg
Content-Length: 124905
<Binary File Data>

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:

    1. Checking the current status of an upload
    2. Resuming a resumable 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:

    PUT <upload_url> HTTP/1.1
    Host: uploads.gdata.youtube.com
    Content-Range: bytes */*
    

    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:

    308 Resume Incomplete
    content-length: 0
    expires: Fri, 01 Jan 1990 00:00:00 GMT
    range: bytes=0-408
    pragma: no-cache
    cache-control: no-cache, no-store, must-revalidate
    date: Fri, 04 Dec 2009 13:45:41 GMT
    content-type: text/html
    

    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:

    PUT <upload_url> HTTP/1.1
    Host: uploads.gdata.youtube.com
    Content-Type: <video_content_type>
    Content-Length: <content_length>
    Content-Range: bytes <first_byte>-<last_byte>/<total_content_length>
    
    <Partial Binary File Data> 
    

    Variables in the resumed upload request

    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.

    The example below shows a sample request to resume an upload:

    PUT /resumableupload/AF8GKF...0Glpk0Aw HTTP/1.1
    Host: uploads.gdata.youtube.com
    Content-Type: video/mpeg
    Content-Length: 124496
    Content-Range: bytes 409-124904/124905
    
    Partial Binary File Data
    

    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.

pagination links

« Previous
Direct Uploading
Next »
Checking a Video's Status

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.