Cloud API

Media API

Here are the descriptions of some fields that you’ll see in this docunentaton.

COUNTRY_CODE: this is a code of two characters to define a country, valid values are fr, us, es, uk, it, etc.. there is a special country code global for worldwide values.

TIME_INTERVAL: this is a time interval, valid values are
  • last_minute
  • last_hour
  • last_day
  • last_week
  • last_month
  • last_year
  • total
ASSET_NAME: they are predefined names linked to an encoding preset, valid values are:
  • source: this is a special asset name as it is the source of the media, basically it is the file that you uploaded
  • flv_h263_mp3: H26# video @380Kbps with MP3 audio @96KBps in a flv container with default size of 320x240
  • mp4_h264_aac_ld: H264 video @180KBps with AAC audio @64KBps in a mp4 container with a max size of 320x240 (iPhone compatible)
  • mp4_h264_aac: H264 video @360KBps with AAC audio @96KBps in a mp4 container with a default size of 512x384 (iPhone compatible)
  • mp4_h264_aac_hq: H264 video @800KBps with AAC audio @128KBps in a mp4 container with a default size of 848x480 (iPhone 4 / iPad compatible)
  • mp4_h264_aac_hd: H264 video @1.5MBps with AAC audio @128KBps in a mp4 container with a default size of 1280x720 (iPhone 4 / iPad compatible)
  • jpeg_thumbnail_small: a jpeg thumbnail with a default size of 80x60
  • jpeg_thumbnail_medium: a jpeg thumbnail with a default size of 160x120
  • jpeg_thumbnail_large: a jpeg thumbnail with a default size of 320x240
  • jpeg_thumbnail_source: a jpeg thumbnail with a maximum width of 848 and a height relative to the frame ratio

Basic operations

create()

Creates a new media object.

This method can either create an empty media object or also download a media with the url paramater and use it as the source to encode the ASSET_NAME listed in assets_names

Parameters:
  • url (url) - (optional) the URL of the source file, this will set the ASSET_NAME source
  • assets_names (Array) - (optional) the list of ASSET_NAME you want to transcode, when you set this parameter you must also set the url parameter
  • meta (Object) - (optional) the dict of metadata
Returns:

the id of the new media object.

Return type:

media ID

The url parameter can be either HTTP or FTP, you can add optionnal authentication informations using the following format: SCHEME://USER:PASSWORD@HOSTNAME/MY/PATH/FILENAME.EXTENSION

It is highly recommended to only use ASCII characters in the URL (no UTF-8 or accentuated characters).

Example request:

{
  "call": "media.create",
  "args": {
    "url": "http://upload-01.dmcloud.net/files/4a4fbbd589952493e357fbb7c1b88ad7.3gp",
    "meta": {
      "author": "john doe",
      "title": "my hollidays"
    },
    "assets_names": [
      "flv_h263_mp3",
      "mp4_h264_aac"
    ]
  },
  "auth": "4c1a4d3edede832bfd000002:25d56cdc1185b0a054f89a17263c1da6",
}

Example response:

{
  "result": {
    "id": "4c9b6917dede8351d600000a"
  }
}
delete()

Delete a media object with all its associated assets.

Parameters:
  • id (media ID) - (required) the id of the media object you want to delete.
Returns:

nothing

Return type:

void

Example request:

{
  "call": "media.delete",
  "args": {
    "id": "4c9b6b4cdede8351d6000019"
  },
  "auth": "4c1a4d3edede832bfd000002:4b37416d65658e91b1057e42ede19545",
}

Example response:

{
  "result": null
}
info()

Gives information about a given media object.

Parameters:
  • id (media ID) - (required) the id of the new media object.
  • fields (Array) - (required) the list of fields to retrieve.
List of valid fields:
  • id : the media id
  • created : the creation date as a unix timestamp
  • embed_url : the url of the embed player
  • frame_ratio : the ratio of the video frame as a float (eg: 16/9, 4/3, etc).
  • stats.global.TIME_INTERVAL : the worldwide statistics on the number of views
  • stats.COUNTRY_CODE.TIME_INTERVAL : the statistics on the number of views in a specific country (eg: stats.fr.total, stats.us.last_week, etc...)
  • extended_stats.COUNTRY_CODE.TIME_INTERVAL
  • meta.KEY : a specific metadata (eg: meta.title)
  • assets.ASSET_NAME.stream_url
  • assets.ASSET_NAME.download_url
  • assets.ASSET_NAME.status
  • assets.ASSET_NAME.container
  • assets.ASSET_NAME.duration
  • assets.ASSET_NAME.global_bitrate
  • assets.ASSET_NAME.video_codec
  • assets.ASSET_NAME.video_width
  • assets.ASSET_NAME.video_height
  • assets.ASSET_NAME.video_bitrate
  • assets.ASSET_NAME.video_rotation
  • assets.ASSET_NAME.video_fps
  • assets.ASSET_NAME.video_fps_mode
  • assets.ASSET_NAME.video_aspect
  • assets.ASSET_NAME.video_interlaced
  • assets.ASSET_NAME.audio_codec
  • assets.ASSET_NAME.audio_bitrate
  • assets.ASSET_NAME.audio_nbr_channel
  • assets.ASSET_NAME.audio_samplerate
  • assets.ASSET_NAME.created
  • assets.ASSET_NAME.file_extension
  • assets.ASSET_NAME.file_size
Returns:a multi-level structure containing about the media related to the requested fields.
Return type:Object

Example request:

{
  "call": "media.info",
  "args": {
    "fields": [
      "id",
      "created",
      "assets.flv_h263_mp3.audio_codec",
      "assets.flv_h263_mp3.download_url",
      "meta.title",
      "id"
    ],
    "id": "4c28a999dede8379b4000034"
  },
  "auth": "4c1a4d3edede832bfd000002:563a3d41c08dd62bccc5c3d24a065d3c",
}

Example response:

{
  "result": {
    "meta": {
      "title": "Big Buck Bunny"
    },
    "created": 1277726073,
    "assets": {
      "flv_h263_mp3": {
        "audio_codec": "MPEG-1 Audio layer 3",
        "download_url": "http://sebest.cdn.dev.int.dmcloud.net/route/4c1a4d3edede832bfd000002/4c28a999dede8379b4000034/flv_h263_mp3-1277726078.flv?cache=0&throttle=0&filename=Big+Buck+Bunny-flv_h263_mp3-1277726078.flv&auth=1285119115-3-gozv3x46-dc5ef3c74798568c3ae7960193c85774"
      }
    },
    "id": "4c28a999dede8379b4000034"
  }
}
list()

Returns a paginated list of media info structures.

You must specify the fields you want to retrieve.

The fields are described in the documentation of the method info.

Parameters:
  • fields (Array) - (required) the fields to retrieve (see the documentation of the info method to know valid fields)
  • page (Integer) - (optional) the page number, default: 1
  • per_page (Integer) - (optional) the number of objet per page, default: 10
Returns:

an object with information for the pagination and the result of the query.

Return type:

Object

Example request:

{
  "call": "media.list",
  "args": {
    "fields": [
      "id",
      "created"
    ],
    "page": 4,
    "per_page": 3
  },
  "auth": "4c1a4d3edede832bfd000002:c422f89f1c079f043629573e42c2e578",
}

Example response:

{
  "result": {
    "list": [
      {
        "id": "4c2ceab0dede8345fa000110",
        "created": 1278004880
      },
      {
        "id": "4c28a7b3dede8379b4000028",
        "created": 1277725587
      },
      {
        "id": "4c1e6f66dede83601700020e",
        "created": 1277055814
      }
    ],
    "page": 4,
    "on_this_page": 3,
    "per_page": 3,
    "total": 531,
    "pages": 177
  }
}

Metadata

set_meta()

Add or replace metadata of a given media object

Parameters:
  • id (media ID) - (required) the id of the media object
  • meta (Object) - (required) an object containing meta as keys and values

Example request:

{
  "call": "media.set_meta",
  "args": {
    "meta": {
      "author": "john doe",
      "title": "my hollidays"
    },
    "id": "4c28a999dede8379b4000034"
  },
  "auth": "4c1a4d3edede832bfd000002:3f84c26bcea7b3e95e7e9373bdb41f4d",
}

Example response:

{
  "result": null
}
get_meta()

Get a list of metadata for a given media object.

If the list of meta is omitted, all metadata are returned.

Parameters:
  • id (media ID) - (required) the id of the media object
  • keys (Array) - (optional) an array of meta you want to retrieve
Returns:

an object containing meta as keys and values

Return type:

Object

Example request:

{
  "call": "media.get_meta",
  "args": {
    "keys": [
      "title"
    ],
    "id": "4c28a999dede8379b4000034"
  },
  "auth": "4c1a4d3edede832bfd000002:9d4298af0b774970643469c6a4efaf55",
}

Example response:

{
  "result": {
    "title": "my hollidays"
  }
}
remove_meta()

Remove a list of metadata key for a given media object

Parameters:
  • id (media ID) - (required) the id of the media object
  • keys (Array) - (required) an array of meta you want to retrieve

Example request:

{
  "call": "media.remove_meta",
  "args": {
    "keys": [
      "author"
    ],
    "id": "4c28a999dede8379b4000034"
  },
  "auth": "4c1a4d3edede832bfd000002:43b3db20ffb9926d1c659f0e21b20813",
}

Example response:

{
  "result": null
}

Media Assets

get_assets()

Get a list of assets with their associated information.

If the list is omitted, all assets are returned.

Parameters:
  • id (media ID) - (required) the id of the media object
  • assets_names (Array) - (optional) a list of assets names
Returns:

assets information as an object

Return type:

Object

Example request:

{
  "call": "media.get_assets",
  "args": {
    "id": "4c28a999dede8379b4000034",
    "assets_names": [
      "source",
      "mp4_h264_aac"
    ]
  },
  "auth": "4c1a4d3edede832bfd000002:d9f09e36dccd2ba18a656064da3fe6cc",
}

Example response:

{
  "result": {
    "mp4_h264_aac": {
      "status": "ready",
      "container": "MPEG-4",
      "created": 1277726081,
      "video_bitrate": 360000,
      "video_height": 240,
      "audio_bitrate": 75084,
      "audio_codec": "AAC LC",
      "file_size": 1957818,
      "duration": 35,
      "video_codec": "AVC",
      "video_width": 320,
      "global_bitrate": 441173
    },
    "source": {
      "status": "ready",
      "video_fps": 29.969999999999999,
      "video_fps_mode": "VFR",
      "container": "MPEG-4",
      "audio_samplerate": 44100,
      "created": 1277726074,
      "video_rotation": 0.0,
      "video_height": 240,
      "file_extension": "mp4",
      "audio_nbr_channel": 2,
      "video_bitrate": 400943,
      "video_aspect": 1.333,
      "video_interlaced": false,
      "audio_bitrate": 69860,
      "audio_codec": "AAC LC-SBR",
      "file_size": 2206378,
      "duration": 35,
      "video_codec": "AVC",
      "video_width": 320,
      "global_bitrate": 497183
    }
  }
}
set_assets()

This method allow you to add new assets either by downloading a media from a given URL, or by transcoding another asset.

Parameters:
  • id (media ID) - (required) the id of the media object
  • assets (Array) - (required) a list of object describing the assets you want
Returns:

nothing

Return type:

void

Assets is a list of object with properties. Valid properties are
  • name (required): this is a valid ASSET_NAME
  • action (optional): this can be either copy or transcode, if no action is specified and the object contains url the action copy will be perform otherwise it defaults to transcode
  • url (optional): the media identified by this url will be downloaded, most of the time it is used with the source ASSET_NAME. It’s also usefull to bypass transcoding.

The url parameter can be either HTTP or FTP, you can add optionnal authentication informations using the following format: SCHEME://USER:PASSWORD@HOSTNAME/MY/PATH/FILENAME.EXTENSION

It is highly recommended to only use ASCII characters in the URL (no UTF-8 or accentuated characters).

Example request:

{
  "call": "media.set_assets",
  "args": {
    "id": "4c9bb4d6dede835e50000006",
    "assets": [
      {
        "action": "transcode",
        "name": "flv_h263_mp3"
      },
      {
        "url": "http://upload-02.dmcloud.net/files/4f6cdb73360bc2913db553d7914d1260.3gp",
        "action": "copy",
        "name": "source"
      },
      {
        "action": "transcode",
        "name": "mp4_h264_aac"
      }
    ]
  },
  "auth": "4c1a4d3edede832bfd000002:18eb9ee1e4ee3049b29125bd959938e0",
}

Example response:

{
  "result": null
}
remove_assets()

Remove a list of assets and their associated information.

If the list is omitted, all assets are removed.

Parameters:
  • id (media ID) - (required) the id of the media object
  • assets_names (Array) - a list of assets names
Returns:

nothing

Return type:

void

Example request:

{
  "call": "media.remove_assets",
  "args": {
    "id": "4c9bb50cdede835e5000000d",
    "assets_names": [
      "flv_h263_mp3",
      "mp4_h264_aac"
    ]
  },
  "auth": "4c1a4d3edede832bfd000002:089a07e2c9f4261569466f8688a7b605",
}

Example response:

{
  "result": null
}
set_thumbnail()

Set the media thumbnail from a URL or from a frame of the source asset.

You can either set a url parameter or a timecode parameter. If url is provided, the thumbnail will be extracted from this URL. If timecode is provied, a frame will be extracted from the source asset at the specified timecode. If both parameter are omitted, a random thumbnail will be automatically exctracted.

Parameters:
  • id (media ID) - (required) the id of the media object
  • url (url) - (option) url of a jpeg image
  • timecode (String) - timecode string, format = HH:MM:SS.mm where HH: 2 digits hours, MM: 2 digits minutes, SS: 2 digits seconds, mm: 2 digits ms
Returns:

nothing

Return type:

void

Example request:

{
  "args": {
    "timecode": "00:01:00.00",
    "id": "4e2ee9f0dede83229000000c"
  },
  "call": "media.set_thumbnail",
  "auth": "4c1a4d3edede832bfd000002:6db02166444d474383072a45e056ac16"
}

Example response:

{
  "result": null
}
set_source()

Set or replace the source of a media.

Parameters:
  • id (media ID) - (required) the id of the media object
  • url (url) - (required) the URL of the source file, this will set the ASSET_NAME source
  • thumbnail - whether to extract (and replace) the thumbnails, default: false
Returns:

nothing

Return type:

void

Example request:

{
  "args": {
    "url": "http://188.65.121.101/files/af6e1c39a01241dc9549ea520fe99e54.3gp",
    "id": "4e2eec1edede83228f00001b"
  },
  "call": "media.set_source",
  "auth": "4c1a4d3edede832bfd000002:858590528ca6df36f1a5f4fafa163afa"
}

Example response:

{
  "result": null
}

File API

Uploading URL

upload()

Return an URL on which you can upload a file using an HTTP POST request.

This URL can then be passed to the media.set_assets or the media.create methods

Parameters:
  • status (Boolean) - (optional) return a status URL to monitor the upload process
  • target (String) - (optional) the URL where you will be redirected after your POST

Example request:

{
  "call": "file.upload",
  "args": {},
  "auth": "4c1a4d3edede832bfd000002:a8fe012836ddd0df62e6403d254b4ae6",
}

Example response:

{
  "result": {
    "url": "http://upload-02.dmcloud.net/upload?uuid=ab91fc66c72a11dfa06f0026b9f94f64&seal=7074b95b20cd5aab0b723e660e419651"
  }
}

Table Of Contents

Previous topic

Uploading media

Next topic

PHP SDK

This Page