This is a simple Python library for interacting with the Vimeo API.

• Get Started
• Help
• Troubleshooting
• Installation
• Usage
  • Authentication / Access Tokens
    • Unauthenticated tokens
    • Authenticated tokens
  • Make requests
  • Uploading videos
    • Uploading a new video
    • Replacing a video source file
  • Upload images
  • Upload a text track

There is a lot of information about the Vimeo API at https://developer.vimeo.com/api/start. Most of your questions will be answered there!

• Stack Overflow
• Google Group
• Vimeo Support

This package is called PyVimeo on PyPI. Install using:

pip install PyVimeo

import vimeo

v = vimeo.VimeoClient(
    token=YOUR_ACCESS_TOKEN,
    key=YOUR_CLIENT_ID,
    secret=YOUR_CLIENT_SECRET
)

# Make the request to the server for the "/me" endpoint.
about_me = v.get('/me')

# Make sure we got back a successful response.
assert about_me.status_code == 200

# Load the body's JSON data.
print about_me.json()

Note: You can find the app tokens and an authenticated bearer token in the "OAuth2" tab for your app on the Vimeo developer site.

There are two main types of authentication in the Vimeo API:

• Unauthenticated - Access tokens without a user. These tokens can only view public data
• Authenticated - Access tokens with a user. These tokens interact on behalf of the authenticated user.

Note: Both types of authentication require you go to the Vimeo developer site and register an application with Vimeo.

Unauthenticated API requests must generate an access token. You should not generate a new access token for each request, you should request an access token once and use it forever.

try:
    # `scope` is an array of permissions your token needs to access.
    # You can read more at https://developer.vimeo.com/api/authentication#supported-scopes
    token = v.load_client_credentials(scope)

    # usable access token
    print 'token=%s' % tkoen
except vimeo.auth.GrantFailed:
    # Handle the failure to get a token from the provided code and redirect.

Getting a bearer token via the authorization code method is a bit more complicated. The most important thing to understand is that we need to go through a series of basic steps:

1. We send the user to a web page where they can choose to accept or reject the permissions we are asking for.
2. When the user makes their selection and accepts or rejects your app, the user is redirected to a webpage specified by you.
3. If the user authorized your app, you can exchange the code provided for the bearer token.

This can be done with this library using some basic helper functions. The code below demonstrates, but do note that there are 2 sections, where you redirect the user to Vimeo, and where the user returns so you can perform the final step.

"""This section is used to determine where to direct the user."""
v = vimeo.VimeoClient(
    key=YOUR_CLIENT_ID,
    secret=YOUR_CLIENT_SECRET
)

vimeo_authorization_url = v.auth_url(
    ['public', 'private'],
    'https://example.com'
)

# Your application should now redirect to `vimeo_authorization_url`.

"""This section completes the authentication for the user."""
v = vimeo.VimeoClient(
    key=YOUR_CLIENT_ID,
    secret=YOUR_CLIENT_SECRET
)

# You should retrieve the "code" from the URL string Vimeo redirected
# to. Here, that's named `CODE_FROM_URL`.
try:
    token, user, scope = v.exchange_code(CODE_FROM_URL, 'https://example.com')
except vimeo.auth.GrantFailed:
    # Handle the failure to get a token from the provided code and redirect.

# Store the token, scope and any additional user data you require in
# your database so users do not have to re-authorize your application
# repeatedly.

This process is generally quite simple, but it does require a little more effort than the client credentials grant to make work properly. Remember that you may ask for scopes that the user decides not to give you, and your application must gracefully handle that.

PyVimeo at its core is a wrapper for Requests, so you can interact with the library as you sould any other object from Requests.

• GET: response = v.get(uri), or with parameters v.get(uri, data={...})
• PATCH: response = v.patch(uri, data={...})
• POST: response = v.post(uri, data={...})
• PUT: response = v.put(uri, data={...})
• DELETE: response = v.delete(uri)

The Vimeo API supports JSON filtering to let you return only the data that you need from an API call. To utilize this with PyVimeo, you can add a fields variable into your endpoint payload, like:

about_me = v.get('/me', params={"fields": "uri,name,pictures"})

Then with this response, you will only receive uri, name, and the pictures object.

Once you have an authenticated instance of the VimeoClient class, uploading is a single function call away with upload. Internally, this library will provide the tus upload and send a local file to the server with the tus upload protocol and tus-python-client.

video_uri = v.upload('your-filename.mp4')

If you wish to add metadata to your video as it's being uploaded, you can supply a data object to .upload().

video_uri = v.upload(
    'your-filename.mp4',
    data={'name': 'Video title', 'description': '...'}
)

Alternatively, you can do this after the video has been uploaded with a patch call.

video_uri = v.upload('your-filename.mp4')

v.patch(video_uri, data={'name': 'Video title', 'description': '...'})

Once you have an authenticated instance of the VimeoClient class, you can also replace the source file of an existing video.

video_uri = v.replace(
    video_uri='video_uri',
    filename='your-filename.mp4'
)

Once you have an authenticated instance of the VimeoClient class, uploading a picture requires only the target object (for instance, the video for which you would like to replace the thumbnail).

v = vimeo.VimeoClient(
    key=YOUR_CLIENT_ID,
    secret=YOUR_CLIENT_SECRET
)

v.upload_picture('/videos/12345', 'your-image.jpg', activate=True)

Note: This will make it the active picture for all users this way. The activate keyword argument defaults to False, so without it you will need to activate the picture yourself.

Once you have an authenticated instance of the VimeoClient class, uploading a text track requires the video uri of the video the text track will be added to, text track type, text track language, and text track filename.

v = vimeo.VimeoClient(
    key=YOUR_CLIENT_ID,
    secret=YOUR_CLIENT_SECRET
)

v.upload_texttrack('/videos/12345', 'captions', 'en-US', 'your-texttrack.vtt')

If you have any questions or problems, create a ticket or contact us

An earlier version of this library used a more complicated ORM syntax. This library is still available from this github repo via the orm-tornado tag.