Prerequisite: After you’ve created your first API application, you can request upload access for your app:


  • Go to https://developer.vimeo.com/apps (My Apps) and click on the name of one of your apps.
  • Choose "Request Upload Access".
  • On the Request Upload Permissions screen, answer the three questions and click "Request Upload Access".
  • You’ll see the message "Requested - Pending decision. You should receive a decision within 5 business days of your request."

Uploading overview

  1. Check the quota: before you can upload you need to make sure the file is not too big
  2. Get a ticket: all upload-related calls need a ticket
  3. Send the video data: you can do this in multiple ways (more on this later)
  4. Verify the transfer: make sure all your data made it to our servers
  5. Complete the upload: tell Vimeo that the data transfer is over and it’s time to encode the video

Which uploading approach should you use?

There are three ways to transfer the video data to us: POSTing the file, streaming the file, or letting us download the file from your server. Which approach you choose depends on the capabilities of the environment you’re working in and your level of comfort with network programming. Here are some considerations:


  • Post: This is the simplest integration; it allows your users to upload directly to Vimeo using a standard HTML form and bypass your server entirely. But if there are any network connectivity errors, the user will have to retry the entire upload. And you can't display a progress bar.
  • Streaming: This is better if you have a more integrated app (like mobile) and want more robust handling of connectivity issues, providing your users with pause, progress bars, and resume. You also have the option to use client-side JavaScript (with the HTML5 File object) to perform and verify the upload, which shifts this work from your server to the user's browser. But streaming is also the most complex approach.
  • Automatic ("Pull"): This is the best (and easiest) approach if the video is already posted on the Internet, at a URL accessible by Vimeo's upload server. All you need to do is provide us with the URL, and we'll automatically grab ("pull") it (and transparently handle any connectivity issues that might arise).

The players in all three approaches are the same:


  • API Provider: Vimeo
  • API Consumer: You
  • User: Client who wants to upload their video to your site

Check user’s quota

The user’s quota is part of their user response. Before you can upload, you’ll need to make sure that uploading the file would not exceed the user’s weekly quota:


  • Basic: up to 500MB of video per week.
  • Plus: up to 5GB of video per week.
  • PRO: up to 20GB of video per week.

The shortcut for the current user is /me:

Request

GET https://api.vimeo.com/me

Response

...
    "upload_quota": {
        "space": {
            "free": 53525865655,
            "max": 53687091200,
            "used": 161225545
        },
        "quota":{
            "hd": true,
            "sd": true
        }
    },
...
Field Description
space.free The amount of bytes left in your quota for the current period
space.max Your maximum quota for the current period
space.used The amount of bytes you have uploaded this period
quota.hd Boolean indicating whether this user can upload an HD video
quota.sd Boolean indicating whether this user can upload an SD video

Simple HTTP POST uploading

In this work flow, you’re making API calls to get an upload ticket, put a form on the page that the client requested, and then wait for client to come back to page. The upload ticket has a chunk of HTML inside the JSON, a form that has a file upload button. When the user clicks the button, the file goes directly from the user's browser to vimeo. If you redirect the user to a different page, the URL will include the video they just uploaded, allowing the owner of the page to pull down video.

  1. Generate an upload ticket

    To upload a new video, make an authenticated POST request to /me/videos.

    Request

    POST https://api.vimeo.com/me/videos
    Field Required Description
    type Yes Must be set to POST.
    redirect_url No Once the upload is complete, the user will be redirected back to this URL. We highly recommend providing a redirect_url.

    Response

    {
        "uri": "/users/12345/tickets/12345",
        "ticket_id": "12345",
        "user": { USER OBJECT },
        "upload_link_secure" : "URL",
        'form': "HTML FORM"
    }
    Field Description
    uri The API endpoint for your upload ticket. You can query this to learn more about the upload.
    ticket_id Your unique ticket id. If you encounter problems uploading, please include this when you contact us.
    user The video you upload to this upload ticket will be associated with this user.
    upload_link_secure A secure (HTTPS) upload URL.
    form An HTML upload form.
  2. Build an HTML form for your user

    Now that you have all of your upload information, you need to build a file uploader and embed it in the HTML of your webpage.

    We recommend you just use the form field of your upload ticket response, it is a fully formed form element. If you need to use custom attributes you should build your own HTML form.

    When building your own form you need to construct two HTML elements. The form element's method must be POST, and the action must be the upload_link_secure from the upload ticket response. Inside that form element you need an input element with a type of file and a name of file_data.

    
    
  3. User uploads video

    Now that the user can see your HTML form, they can use it to upload their video

    Once the user's browser completes the upload, the server will redirect them to your previously provided redirect_url. We will retain any parameters you have provided, and add one new parameter video_uri. This URI will point to the new video resource.

    This upload depends entirely on the client’s browser. If you want resumable uploads, you need to integrate Resumable HTTP PUT uploads.

Resumable HTTP PUT uploads

In this work flow, when the upload ends, you evaluate the number of bytes we’ve received so far to determine if the entire file's been uploaded. The upload can end for three reasons: the request times out, the upload completes successfully, or an error was encountered with the server. Once the file has uploaded successfully, you need to delete the upload ticket by making a delete request to the URL. The response to this delete request will contain a location header that contains the video URI.

  1. Generate an upload ticket

    To upload a new video, make an authenticated POST request to /me/videos. The response will contain all necessary information about your upload ticket. You must set the type parameter to streaming.

    Request

    POST https://api.vimeo.com/me/videos
    Field Required Description
    type Yes Must be set to streaming.

    Response

    {
        "uri": "/users/12345/tickets/12345",
        "complete_uri": "/users/12345/tickets/12345?key=value",
        "ticket_id": 12345,
        "user": { USER OBJECT },
        "upload_link_secure" : "URL"
    }
    Field Description
    uri The API endpoint for your upload ticket.
    complete_uri The URI you use when finishing the upload. You will make an HTTP DELETE request to this endpoint. The response to this delete request will contain a location header that contains the video URI.
    ticket_id Your unique ticket ID. If you encounter problems uploading, please include this when you contact us.
    user The video you upload to this upload ticket will be associated with this user.
    upload_link_secure A secure (HTTPS) upload URL.
  2. Upload your video

    To stream an upload to Vimeo, perform a PUT call to upload_link_secure with headers specifying the Content-Length and Content-Type. Our CORS security policy limits the allowed headers, so unnecessary headers like `Authorization` should not be included in requests. Here’s an example HTTP request:

    Request

    PUT https://1234.cloud.vimeo.com/upload?ticket_id=abcdef124567890

    Request Body

    Host: 1.2.3.4:8080
    Content-Length: 339108
    Content-Type: video/mp4
    .... binary data of your file here ....

    Successful uploads with have a HTTP 200 status code. A 501 error means you did not perform a PUT or the request was malformed.

  3. Verify the upload

    To check how much of a file has transferred, perform the exact same PUT request without the file data and with the header "Content-Range: bytes */*". Here’s an example request:

    PUT https://1234.cloud.vimeo.com/upload?ticket_id=abcdef124567890
    Host: 1.2.3.4:8080
    Content-Length: 0
    Content-Range: bytes */*

    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 three but with an additional header:

    Content-Range: bytes (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: bytes */*" 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:

    PUT https://1234.cloud.vimeo.com/upload?ticket_id=abcdef124567890
    Host: 1.2.3.4:8080
    Content-Length: 338108
    Content-Type: video/mp4
    Content-Range: bytes 1001-339108/339108
    .... binary data of your file here ....

    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.

  4. Complete the upload

    To complete your upload, you need to make one last verify check. If everything looks good, you can make an HTTP DELETE request on your complete_uri.

    DELETE https://api.vimeo.com{complete_uri}

    The response of this delete request will contain the new video uri in the Location header

Automatic ("pull") uploads

Pull has just one step: Make the initial request to get the upload ticket, setting type=pull and providing a link to a video on the Internet that is accessible to Vimeo’s upload server. When our servers receive this request, we make a quick check to make sure you’ve sent us a video file. If it is a valid video file, you’ll immediately receive a full response, including the title and URI.

POST https://api.vimeo.com/me/videos
Field Required Description
type Yes Must be set to pull.
link Yes A url to a video file accessible by Vimeo's servers.

Replace source file

When you replace a video's source file, the video will retain all settings, thumbnails, and URLs from the original video. The process necessary to replace a source file is nearly identical to the process necessary to upload a video. The only difference is the initial HTTP request.

  1. Make an HTTP PUT request to your video's files URI.

    PUT https://api.vimeo.com/videos/{video_id}/files

    This supports all of the same parameters as streaming, POST, and pull uploads and will return an identical response.

  2. Start uploading your video

Send Feedback