Upload API

The first thing you need to do is request upload access for your application. You can do so from your My Apps page.

Overview

Check the quota: before you can upload you need to make sure the file is not too big

Get a ticket: all upload-related calls need a ticket

Send the video data: you can do this in multiple ways (more on this later)

Verify the transfer: make sure all your data made it to our servers

Complete the upload: tell Vimeo that the data transfer is over and it’s time to encode the video

We’ll get into specifics below on exactly which calls are involved for each step, but before we begin there’s one more thing you need to know. There are two ways to transfer the video data to us: either by POSTing the file or streaming the file.

Which approach you choose depends on the capabilities of the environment you’re working in and your level of comfort with network programming. If you are working on a totally web-browser based uploading interface you will have to use POST approach. If you are working on a more integrated application (such as a mobile app) or need robust resumable uploading, we recommend streaming. Both flows are described in detail below.

Uploading via streaming

Streaming is a more efficient way to transfer video data to our upload servers. Instead of generating a multipart POST, a standard HTTP connection is opened and the binary data of the file is simply written into the socket. This is often much more efficient on the client side because it requires no manipulation of the file data. However, it requires more network programming experience and the ability to read headers.

Check the user’s quota

Before you begin call vimeo.videos.upload.getQuota to make sure the user has enough space available in their account and to let them know if their video will be encoded in HD.

Get an upload ticket

Before you can upload a video you’ll need an upload ticket. You can get one by calling vimeo.videos.upload.getTicket with the upload_method parameter set to streaming. You should receive a response with a ticket id and an endpoint. Here is an example response in JSON (you can specify the response format):

Transfer the video data

If more than a few hours have passed since your ticket was generated, make sure to call vimeo.videos.upload.checkTicket to make sure your ticket is still valid.

To stream an upload to Vimeo you must perform a PUT call to the endpoint with headers specifying the Content-Length and Content-Type. Content-Length is simply the size of your file. Other headers are OK, they’re just ignored. Here’s an example of the format of the HTTP request.

If this file exists, this will return a response with a HTTP 308 status code and a Range header with the number of bytes on the server.

HTTP/1.1 308
Content-Length: 0
Range: bytes=0-1000

If you perform a request like this and find that the returned number is NOT the size of your uploaded file, then it’s a good idea to resume where you left off. To resume, perform the same PUT you did in step 3 but with an additional header with the following string format: "Content-Range: (last byte on server + 1)-(last byte I will be sending)/(total filesize)". As shown in the example above, our uploaded file was 339108 total bytes in size but our "Content-Range: */*" verification call returned a value of 1000. To resume we would send the following headers with the binary data of our file starting at byte 1001:

If all goes well you will receive a 200 status code. A 400 code means the Content-Range header did not resume from the last byte on the server.

Complete the upload

The final step is to call vimeo.videos.upload.complete to queue up the video for transcoding. This call will return the video_id, which you can then use in other calls (to set the title, description, privacy, etc.). If you do not call this method, the video will not be processed.

Uploading via POST

POST is the standard way for web browsers to transfer large files. If you’re working in an environment that has robust built-in support for multipart POSTs (such as an Adobe AIR app), this is a good solution for you. If you want to provide a way for users to upload directly to Vimeo via a web page this is the only way to do it.

Check the user’s quota

Before you begin call vimeo.videos.upload.getQuota to make sure the user has enough space available in their account and to let them know if their video will be encoded in HD.

Clearly this is a very verbose and quirky format, so unless you’re working in a browser or a language that has robust POST support, we recommend trying the streaming approach to uploading (see below).

You may have noticed the chunk_id parameter. Vimeo’s upload system allows multiple chunks of a file to be uploaded via POST and reassembled on the server. This is useful for resuming uploads or splitting up a file and uploading many parts in parallel. chunk_ids should be assigned in the order you want them combined, starting with 0.

Verify the upload

Call vimeo.videos.upload.verifyChunks to get a list of the chunks uploaded and their associated filesizes. You can use this to verify that everything arrived correctly. If you find that the uploaded file’s size is wrong, you can replace it by running the POST again with the same chunk_id. Or if an upload was accidentally terminated, you could check where the upload left off and POST the remainder of the file with an incremented chunk_id.

Here’s an example XML response for an upload with 3 chunks, the chunk IDs correspond to the chunk_id you assigned when POSTing the chunk in step 3.

Complete the upload

The final step is to call vimeo.videos.upload.complete to queue up the video for transcoding. You’ll receive back the video_id from this call, which you can then use in other calls (set the title, description, privacy, etc.). If you do not call this method, the video will not be processed.