Documentation

Upload images, videos, audio

media.upload

The media upload API call ingests, transcodes, and hosts content for you.  You can use the HTTP POST method using multipart/form data and include the content to be ingested as (explain) in a 'file' field.  If you prefer, and the content file is available publicly via HTTP, you can specify a URL in the API call, and the Mogreet platform will retrieve the file from that location, transcode, store and host the data.

In either case, the API call returns to you a 'smart URL' which identifies the content you submitted. When you use that smart URL in a mobile message, social application, mobile phone app, web or mobile web page, etc, the Mogreet platform detects the device type which is requesting the content, selects the most appropriate version of the content for that device, and delivers the correct data from a global CDN.  All you need to do is ingest the content via the media.upload API, the Mogreet platform does all the transcoding, hosting and serving for you transparently.

media types supported

You can upload Audio, Video, and Images into the platform.  When POST Upload, the mime types are used to validate the media prior to upload. The following mime types are accepted:

Video Audio Image
video/quicktime audio/basic image/jpeg
video/x-msvideo audio/x-au  
video/x-ms-wmv audio/mpeg more coming soon!
video/avi audio/x-mpeg  
video/mp4 audio/mp3  
video/mp4v-es audio/x-mp3  
video/mpeg audio/mpeg3  
video/x-m4v audio/x-mpeg3  
video/3gpp audio/mpg  
application/x-3gp audio/x-mpg

When you ingest content with a direct post, the data arrives as an octet-stream, and cannot be checked for supported media until we attempt transcoding. At that point, we support 99% or better of the LibAVCodecs found here:

http://en.wikipedia.org/wiki/Libavcodec

Failures during this phase of the upload can be detected with callbacks.

callbacks

You can also specify an optional callback URL in the API call. When you specify a callback URL, the status of the upload, ingest and transcode will be passed back to that URL when the Mogreet platform completes the work. This is useful for confirming that the content is ready for use, and for catching failures and errors in transcoding that might be caused by a corrupt file, unsupported type, or other unknown problem.

Request:

https://api.mogreet.com/cm/media.upload

with the following parameters:

Name Description
client_id Your client id.
token Your token.
type the media type of the content file, one of: audio, image, video The API uses this to pre-validate the file extension prior to ingesting it. The observed filetype of the file (.png, .jpg, .mov, etc) should be appropriate for the type described in this field. If there is a mismatch, an error will be returned (see below).
name A descriptive name to be used in the media.list and other areas to describe the media content. This can be different than the filename.
file (optional) The actual data file payload to ingest: the image file, audio file or video file. This field is used when POSTing multi-part form data. It can be omitted if you are using the URL ingestion method.
url (optional) When you wish to ingest a media file which is already hosted somewhere on the internet, you can use this option instead of the POST multi-part form method. The URL should identify a file hosted at a fully qualified domain, and be publically available without login or other security.
callback_url (optional) If you specify a callback_url, a message indicating success or failure will be delivered to the location specified, as an XML document. See below for examples.

A successful call will return an HTTP 200 with XML response as detailed below.
For this example call:
https://api.mogreet.com/cm/media.upload?client_id=12345&token=e15b909234f6836eab1cb0&url=http://www.mysite.com/video/nice_car.mp4&type=video&name=VideoFromUrl
this will be the result

Name Descripton
complete response
<?xml version="1.0" encoding="UTF-8"?>
<response code="1" status="success">
<message>media correctly uploaded</message>
<media>
<name>lancia_037</name>
<content_id>154570</content_id>
<smart_url>http://m.mogreet.com/oc/iw9l2mf59</smart_url>
</media>
</response>
name
The name of the content item given at the time the content was ingested
smart_url
a URL which will resolve to the correct version of the content for any media device.  You can test a smart URL by pasting it into a web browser. 
http://m.mogreet.com/oc/iw9l2mf59

Here is an example call using the multi-part/form encoding, using curl. Curl is a great way to test the upload command while in development.

curl -F "file=@myvideo.mp4" "https://api.mogreet.com/cm/media.upload?client_id=12345&token=e15b909234f6836eab1cb0&type=video&name=VideoPostFromCurl"

Here is an example API command, using curl, with the optional callback_url specified. That URL will receive an XML document describing the status and result when the upload and transcode is complete.

curl -F "file=@myvideo.mp4" "https://api.mogreet.com/cm/media.upload?client_id=12345&token=e15b909234f6836eab1cb0&type=video&name=VideoCallback&callback_url=http://labs.mogreet.com/api_callback"


Here are some examples of errors you might encounter:

Request Response
an improper filetype
<?xml version="1.0" encoding="UTF-8"?>
<response status="error" code="462">
<message>
<![CDATA[Your video is in an unsupported format.]]>
</message>
</response>

the file was larger than the upload size limit of 150 MB.
<?xml version="1.0" encoding="UTF-8"?>
<response status="error" code="461">
<message>
<![CDATA[Maximum file size exceeded. Please keep the file under 150MB.]]>
</message>
</response>

invalid media, name too long!
<?xml version="1.0" encoding="UTF-8"?>
<response status="error" code="463">
<message>
<![CDATA[Name is too long (maximum is 50 characters)]]>
</message>
</response>


media.destroy

The media.destroy API command takes a content_id, and then flags it for deletion. Content deletion happens daily, at which time all versions will be purged from the CDN and hosting services, and the records of the versions will be deleted. Up until deletion occurs the content will still be available via the smart URL. After deletion, any request to that smart URL will receive a special 'not available' content item.

Request:

https://api.mogreet.com/cm/media.destroy

with the following parameters:

Name Description
client_id Your client id.
token Your token.
content_id The content id of the content item you want removed from the system. After deletion that content item will no longer be available. There is no undo.

See the full API reference for more info: Mogreet Messaging System API 4.01.pdf