API Tutorial

Introduction

The purpose of this tutorial is to allow you to easily use the Dailymotion Cloud Python API.

Connecting

First we connect to the API. We use the API informations (user ID and API key) provided in the web interface under Account / Profile. The API endpoint is http://api.dmcloud.net.

Here is an example:

from cloudkey import CloudKey
BASE_URL = 'http://api.dmcloud.net/api'
USER_ID = '4e268e8194a6f67e29000156'
API_KEY = '63ab5b0610d5f4c5f8126abc492606ee058f2498'
cloudkey = CloudKey(USER_ID, API_KEY, BASE_URL)

Adding a media

We want to add a media, so we need to upload a media file:

media_info = cloudkey.file.upload_file(file='my_holidays_in_istanbul.3gp')

Then we create a media:

media_id = cloudkey.media.create()['id']

Adding media informations

We set a metadata ‘title’:

media_title = media_info['name'].replace('_', ' ')
cloudkey.media.set_meta(id=media_id, meta={'title': media_title})

We set other informations:

cloudkey.media.set_meta(id=media_id, meta={'type': 'video', 'category': 'travel'})

Manage media assets

We set the video that we just uploaded as the source of our media:

media_url = media_info['url']
cloudkey.media.set_assets(id=media_id, assets=[{'name': 'source', 'url': media_url}])

The process can take some time, according to the source media we uploaded, so we may need to wait for the asset to be set. This example function retrieves an asset to check its status and blocks until it’s ready or failed:

def wait_for_asset(media_id, asset_name):
    while True:
        asset = cloudkey.media.get_assets(id=media_id, assets_names=[asset_name])[asset_name]
        if asset['status'] != 'ready':
            if asset['status'] == 'error':
                print 'Asset couldn\'t be processed!'
                return False
            print '%s not ready: %s' % (asset_name, asset['status'])
            time.sleep(5)
            continue
        print '%s ready' % asset_name
        return True

Let’s wait:

wait_for_asset(media_id, 'source')

We need different viewing qualities for our users, so we encode our source in two asset_name and wait for them to finish:

cloudkey.media.set_assets(id=media_id, assets=[{'name': 'flv_h263_mp3'}, {'name': 'mp4_h264_aac'}])
wait_for_asset(media_id, 'flv_h263_mp3')
wait_for_asset(media_id, 'mp4_h264_aac')

Notice that we could have used a quicker way to publish a video:

media_ = cloudkey.media.create(url=media_url, assets_names=['flv_h263_mp3', 'mp4_h264_aac'], meta={'title': media_title, 'author': 'John Doe'})

We may want to change the thumbnails. It is possible to do so by using a url to a jpeg file:

cloudkey.media.set_thumbnail(id=media_id, url='http://t3.gstatic.com/images?q=tbn:ANd9GcT4cebUDh0VtSjfE_HXg7t9tsTpriGkRFn5AnK7ti07XzpkKhJY', force=True)

or an image from our source by giving a timecode in the media:

cloudkey.media.set_thumbnail(id=media_id, timecode='00:00:05.00', force=True)

Listing the media

We can list the different assets we just set, this way:

print cloudkey.media.get_assets(id=media_id)

We can get a list of all our media IDs:

print [d['id'] for d in cloudkey.media.list(fields=['id'])['list']]

Also, we can get some other informations about our media:

for m in cloudkey.media.list(fields=['id', 'meta.title', 'assets.flv_h263_mp3.stream_url', 'created'])['list']:
    print m

Playing the media

Now that our media is set up, it is ready to be played by our users.

We can retrieve the stream URL of a specific asset_name, by doing so:

print cloudkey.media.info(id=media_id, fields=['assets.flv_h263_mp3.stream_url'])

To get the embed URL, we can use:

print cloudkey.media.info(id=media_id, fields=['assets.flv_h263_mp3.embed_url'])

Getting the media statistics

Our media is up and ready, our users are happy, but we need to know some statistics about the views.

We can get the number of views, by country for the past 12 months, this way:

print cloudkey.media.info(id=media_id, fields=['stats.global.last_year'])

Getting the accounting statistics

Now, we would like to know our storage and streaming usage, on a daily, monthly or alltime basis. We are going to use the methods get_storage() and get_streaming(), which take as arguments some unix timestamps, and a precision which can be daily, monthly or alltime. So, we first need to set a time range, for instance:

import time
end = int(time.time())
begin = end - 3600 * 24 * 365

Then, in order to get the storage usage for a daily precision:

print cloudkey.accounting.get_storage(begin=begin, end=end, fields=['volume', 'duration', 'count'], precision='daily')

Here is an example to get the streaming usage:

print cloudkey.accounting.get_streaming(begin=begin, end=end, type=1, fields=[volume', 'duration'], precision='monthly')

It is also possible to omit the begin and end arguments:

print cloudkey.accounting.get_streaming(type=1, fields=['volume', 'duration'], precision='monthly')

Deleting the media

For some reason, we want to remove the media we just set:

cloudkey.media.delete(id=media_id)