Vid.ly API Questions

Interested in retrieving view stats for your Vid.lys? We have just the thing for you! You can use the GetStatistics call to the API to return the following data:

     <col>Class</col>
     <col>Vendor</col>
     <col>Model</col>
     <col>Platform</col>
     <col>OS</col>
     <col>Browser</col>
     <col>Browser Ver</col>
     <col>Views</col>

Vid.ly's GetStatistics will return following data for a individual vid.ly or system wide:

System wide:

<?xml version="1.0"?>
<Query>
<Action>GetStatistics</Action>
<UserID>1</UserID>
<UserKey>***</UserKey>
<Filter>
<StartDate>2011-11-01</StartDate>
<StartDate>2011-11-30</StartDate>
<UserID>user_id</UserID>
</Filter>
</Query>

Or if you need to narrow it by certain URL then you add  <MediaURL> :

<?xml version="1.0"?>
<Query>
<Action>GetStatistics</Action>
<UserID>1</UserID>
<UserKey>***</UserKey>
<Filter>
<StartDate>2011-11-01</StartDate>
<StartDate>2011-11-30</StartDate>
<mediaurl>mediaurl</mediaurl>
</Filter>
</Query>

If you're a current Encoding.com customer, utilizing our API to create content, try adding this to the mix:

<format>
    <!-- Format fields -->
    <output>vidly</output>
    <vidly_destination>[aws|rs]</vidly_destination>
</format>

You're create a URL that can be accessed via any browser with the correct, optimized version served up whether its a mobile, ipad or browser. 

Have more questions about Vid.ly? Perhaps...what's it all mean? Look no further: http://m.vid.ly/user/

Want to update an existing Vid.ly URL with new source content. Very simple! Via API you can use the UpdateMedia call along with the shortlink and you're ready to roll.

Take a look at the following example:

<?xml version="1.0"?>
<query>
<action>UpdateMedia</action>
<userid>[userid]/userid>
<userkey>[userkey]</userkey> 
<notify>[email_or_URL]</notify>
<source>
<mediashortlink>[mediashortlnk]</mediashortlink>
<sourcefile>[sourcefile]</sourcefile> <--- Put new source file link here
</source>
</query>

You'll want to wait to receive a notify back from the API that the media has processed succesfully, before proceeding with viewing.

We've recently published an Objective C wrapper for the Vid.ly API  that will jump start your iOS application video development.  Now you can utilize vid.ly within your iOS apps to not only transcode any user generated video upload but also prepare vid.ly URLs or embed code to ensure any video will playback brilliantly on over 6000 mobile devices.  The Objective C wrapper includes helper methods for all important vid.ly actions (AddMedia, DeleteMedia and GetStatus)   Download and enjoy!

https://github.com/0xcefaedfe/libVidly

The Vid.ly API can be used to obtain status information on jobs, by BatchID or MediaShortlink:

<?xml version="1.0"?>
<query>
  <action>GetStatus</action>
  <userid>[UserID</userid>
  <userkey>[User_Key]</userkey> 
<notify>[User_Email]</notify>
<BatchID>[BatchID_or_MediaShortlink]</BatchID>
</query>

Response:

<?xml version="1.0"?>
<Response>
<Message>[Success]</Message>
<MessageCode>[MessageCode]</MessageCode>
<Success>
<Task>
<UserID>[UserID]</UserID>
<MediaShortLink>[MediaShortLink]</MediaShortLink>
<SourceFile>[SourceFile]</SourceFile>
<BatchID>[BatchID]</BatchID>
<Status>[Status]</Status>
<Created>[LinkCreatedDate]</Created>
<Updated>[LinkUpdatedDate]</Updated>
<UserEmail>[UserEmail]</UserEmail>
</Task>
<Task>
</Task>
</Success>
<Errors> <!-- if file is not in Success section, it must be in this one -->
<Error>  <!-- Relates to the appropriate SourceFile in the request list -->
<SourceFile>[SourceFileK]</SourceFile>
<ErrorCode>[ErrorCodeID]</ErrorCode>
<Description>[ErrorDescriptionK]</Description>
<Suggestion>[ErrorSuggestionK]</Suggestion>
</Error>
</Response>

MessageCodes? ErrorCodes? What's the difference you may ask? MessageCodes give you particular feedback as to the status of the actions you have requested from the API. (We're talking about AddMedia, AddMediaLite, etc.) Error codes are more or less what you'll bump into if the system has an issue crunching on your files. They follow the same breakdown as the message codes, Common Errors (I), AddMedia codes (II), DeleteMedia codes (III)  and GetStatus codes (IV).

1. Common parameters errors

1.1 - "Wrong XML format."
Request was sent in a wrong XML format, so we could not parse it. Check that your XML format is valid and compliant to XML specification.

1.2 - "Wrong UserID given."
Your UserID is either empty or not present in the database. Check your UserID.

1.3 - "Wrong UserKey given."
Your UserKey either is empty or does not fit given UserID. Check that your UserKey is valid and fits your UserID.

1.4 - "Account is blocked."
Your account was blocked by the administrator. Contact the site administrator to get more information and help.

1.5 - "Account type does not permit this operation."
Your account type does not allow you to proceed this operation. You will get a full access to the API functions of the site with Pro account.

1.6 - "Wrong action name."
The action name you provided is either empty or not valid. Check the correctness of the given action name and make sure that such action exists.

1.7 - "Only one notify tag is allowed."
You may use only one notify tag in request. If any notify tags are provided, only the first one will be used. The other notifies will be omitted.

Ⅱ. AddMedia parameters errors

2.1 - "No source links provided."
You have not provided any source links in your request or all source links are invalid. Check that you have provided valid source files links in your request.

2.2 - "Wrong source file link."
Provided source file link is wrong. Check the correctness of the source file link.

2.3 - "No Output tag or more than one Output tag is provided for the format.."
An Output tag was not provided or more than one Output tag is given. You should provide one correct Output tag for your format.

Ⅲ. DeleteMedia parameters errors

3.1 - "No media short links provided."
You have not provided any media short links in your request or all media short links are invalid. Check that you have provided valid media short links in your request. If you have used batch ID, verify that it contains any media links (you may need to consult site administrator for this).

3.2 - "Wrong media short link."
Provided media short link is wrong. Check the correctness of the media short link.

3.3 - "Wrong batch ID provided."
Batch ID you provided is not correct or does not exist. Check the correctness of the batch ID and make sure you (or somebody else) have not deleted it.

3.4 - "Given batch ID does not contain any media short links."
There are no media short links associated with this batch. Probably, all links have been already deleted or file upload failed.

3.5 - "You are not allowed to delete this media."
You are not allowed to delete this media because it was not uploaded by you. Make sure that you are using the appropriate authentication data.

3.6 - "Media short link was not deleted properly."
We have tried to delete this media short link, but it was not deleted properly. This may happen because of some internal problems. Though link is not valid anymore, some records or files may still be alive. We shall try to complete this task automatically a bit later.

3.7 - "Media short link has been already deleted."
The media short link you have requested has been already deleted. You (or someone else) has already deleted this link. It cannot be deleted twice.

Ⅳ. GetStatus parameters errors

4.1 - "No media short links provided."
You have not provided any media short links in your request or all media short links are invalid. Check that you have provided valid media short links in your request. If you have used batch ID, verify that it contains any media links (you may need to consult site administrator for this).

4.2 - "Wrong media short link."
Provided media short link is wrong. Check the correctness of the media short link.

4.3 - "Wrong batch ID provided."
Batch ID you provided is not correct or does not exist. Check the correctness of the batch ID and make sure you (or somebody else) have not deleted it.

4.4 - "Given batch ID does not contain any media short links."
There are no media short links associated with this batch. Probably, all links have been already deleted or file upload failed. Try to reload media files once again and use new batch ID. If this fails, contact site administrator.

4.5 - "You are not allowed to get status of this media."
You are not allowed to get status of this media because it was not uploaded by you. Make sure that you are using the appropriate authentication data.

4.6 - "Media short link uploaded with errors."
Some error occurred at uploading this media, so this link is nonoperating. This error may have happened due to some internal server error at uploading media or because of some file format incompatibilities. Please try to upload your media once again. If this fails, contact site administrator.

4.7 - "Media short link was deleted."
The media short link you have requested was deleted. No files associated with this link are valid anymore. If you want to use them, please reload these files and use new link.

Ⅴ. Common errors

5.1 - "Action failed because of internal reasons."
Action failed because of some internal reasons. This may happen because of bad Internet connection or some internal server error. Please try again a bit later.

Let's take a look at typical XML repsonse to fully understand MessageCodes.  In this example, line 4 contains the MessageCode 2.1. Let's skip to the chart below the XML to read more about the types of MessageCodes exist.

<?xml version="1.0"?> 
<Response> 
<Message>All medias have been added.</Message> 
<MessageCode>2.1</MessageCode> 
<BatchID>[unique_id]</BatchID> 
<Success> 
<MediaShortLink> 
<SourceFile>[SourceFile1]</SourceFile> 
<ShortLink>[Vid.ly_shortlink1]</ShortLink> 
</MediaShortLink> 
<MediaShortLink> 
<SourceFile>[SourceFile2]</SourceFile> 
<ShortLink>[Vid.ly_shortlink2]</ShortLink> 
</MediaShortLink> 
</Success> 
<Response>

The XML response statuses codes are broken down into 4 categories, Common Errors (I), AddMedia codes (II), DeleteMedia codes (III)  and GetStatus codes (IV). In the case of the above XML, the MessageCode 2.1 is definately a good one to receive back from the system. Keep an eye on these codes as they can give particular insight into why your Vid.lys fail or your XMLs are not accepted.

- - -

Ⅰ. Common error occured

1.1 - "Action failed: wrong query info."

1.2 - "Action failed because of some internal reason."

Ⅱ. AddMedia action

2.1 - "All medias have been added."

2.2 - "Action completed with errors: some files failed to upload."

2.3 - "Action failed: none of files were uploaded."

Ⅲ. DeleteMedia action

3.1 - "All medias have been deleted."

3.2 - "Action completed with errors: some media short links are wrong."

3.3 - "Action failed: all media short links are wrong."

3.4 - "Action failed: batch ID is wrong."

3.5 - "Action failed: batch is empty."

3.6 - "Action completed with errors: some media short links were not deleted properly."

Ⅳ. GetStatus action

4.1 - "Action successful."

4.2 - "Action completed with errors: some media short links are wrong."

4.3 - "Action failed: all media short links are wrong."

4.4 - "Action failed: batch ID is wrong."

4.5 - "Action failed: batch is empty."

If you wish to remove Vid.lys, you may do so via API. There are two ways you can achieve this, via BatchID or via Shortlink. 

To remove via shortlinks:

<?xml version="1.0"?>
<query>
  <action>DeleteMedia</action>
  <userid>[User_ID]</userid>
  <userkey>[User_Key]</userkey>
  <notify>[email_or_URL]</notify>
<MediaShortLink>[MediaShortLink1]</MediaShortLink>
<MediaShortLink>[MediaShortLink2]</MediaShortLink>
<MediaShortLink>[MediaShortLink3]</MediaShortLink>
<MediaShortLink>[MediaShortLink4]</MediaShortLink>
<MediaShortLink>[MediaShortLink5]</MediaShortLink>
</query>

Now, let's try the same call, but we'll use the BatchID tag:

<?xml version="1.0"?>
<query>
  <action>DeleteMedia</action>
  <userid>[User_ID]</userid>
  <userkey>[User_Key]</userkey>
  <notify>[email_or_URL]</notify>
<BatchID>[BatchID]</BatchID>
</query>

Where oh where do we find at BatchID you say? In your response XML from a batch submit, use the ID you receive in the callback as we see in this example in line 5.

<?xml version="1.0"?> 
<Response> 
<Message>All medias have been added.</Message> 
<MessageCode>2.1</MessageCode> 
<BatchID>[unique_id]</BatchID> 
<Success> 
<MediaShortLink> 
<SourceFile>[SourceFile1]</SourceFile> 
<ShortLink>[Vid.ly_shortlink1]</ShortLink> 
</MediaShortLink> 
<MediaShortLink> 
<SourceFile>[SourceFile2]</SourceFile> 
<ShortLink>[Vid.ly_shortlink2]</ShortLink> 
</MediaShortLink> 
</Success> 
</Response>

Want to send a batch request and convert a ton of source files to vid.lys all at one time? Use the following formatting to achieve this.

<?xml version="1.0"?>
<query>
  <action>AddMedia</action>
  <userid>[User_ID]</userid>
  <userkey>[User_Key]</userkey>
  <notify>[email_or_URL]</notify>
<Source>
<SourceFile>[SourceFile1]</SourceFile>
<CDN>[CDNType]</CDN>
</Source><Source>
<SourceFile>[SourceFile2]</SourceFile>
<CDN>[CDNType]</CDN>
</Source>
</query>

Your response will be as follows:

<?xml version="1.0"?>
<Response>
  <Message>All medias have been added.</Message>
  <MessageCode>2.1</MessageCode>
  <BatchID>[unique_id]</BatchID>
  <Success>
   <MediaShortLink>
    <SourceFile>[SourceFile1]</SourceFile>
    <ShortLink>[Vid.ly_shortlink1]</ShortLink>
   </MediaShortLink>
   <MediaShortLink>
    <SourceFile>[SourceFile2]</SourceFile>
    <ShortLink>[Vid.ly_shortlink2]</ShortLink>
   </MediaShortLink>
  </Success>
</Response>

Vid.ly Lite is accessed by a simple change to the Vid.ly standard API call. Instead of <action>AddMedia</action>, use <action>AddMediaLite</action>.  This API call is designed for customers who do not want to incur the ongoing storage expense of all 24 of our standard web and mobile output formats and are less concerned with complete mobile device coverage.  When called AddMediaLite will generate the following 5 output formats (instead of our standard 24 when using AddMedia)  The 5 output formats are listed below with (corresponding devices or browsers each formats is mapped to):

1. 800 Kbps @ 0x360 mp4 for the iPhone 4G, iPad, Safari, IE (H.264 main profile)
2. 800 Kbps @ 0x360 webm for  Firefox, Chrome, Android (VP8)
3. 800 Kbps @ 0x360 flv for the Flash fallback (H.264 main profile)
4. 400 Kbps @ 0x240 mp4 H.264 baseline profile for all 3G mobiles including iPhone 3G
5. 1200 Kbps @ 0x576 mp4  H.264 high profile for best quality iPad HD video

For more information see the Vid.ly API documentation

With Vid.ly, we create 5 thumbnail images and provide direct http access to them for use within your HTML or application.  Here are the details:

2 X Poster Images:  Width = 640 pixels and the height is resized proportionally to your source video dimensions.  The poster image is used as the default image displayed within the player before the user clicks the play button. First poster image is taken at 10% mark of the duration of the source video and the second one is taken at the 00:00:01 time stamp of the video.  To obtain the image @ 00:00:01, please use http://cf.cdn.vid.ly/5u4h3e/link.jpg, where "5u4h3e" is your individual vid.ly url code. To access the poster image at the 10% mark, please use http://cf.cdn.vid.ly/5u4h3e/poster.jpg.

3 X Thumbnails Images:  All three have the width of 210 pixels and the height is resized proportionally to your source video dimensions.  The three thumbnails are taken at the 33%, 66%, and 90% duration marks of your source video and can be accessed directly by using http://cf.cdn.vid.ly/5u4h3e/thumbnail_1.jpg,  http://cf.cdn.vid.ly/5u4h3e/thumbnail_2.jpg, or http://cf.cdn.vid.ly/5u4h3e/thumbnail_3.jpg  Where "5u4h3e" is your individual vid.ly url code.

If you've selected Rackspace as the CDN for Vid.lys created via the API, the formatting for thumbnails will look a little different. Format your URLs to pull thumbnails as follows. Just make sure to swap out the shortlinks! This reformatting guide below will help alleviate any pains caused by Access Denied errors on attempts to pull thumbnails.

Poster Images:

http://c197913.r13.cf1.rackcdn.com/5c5l3c/poster.jpg

http://c197913.r13.cf1.rackcdn.com/5c5l3c/link.jpg

Thumbnail Images:

http://c197913.r13.cf1.rackcdn.com/5c5l3c/thumbnail_1.jpg

http://c197913.r13.cf1.rackcdn.com/5c5l3c/thumbnail_2.jpg

http://c197913.r13.cf1.rackcdn.com/5c5l3c/thumbnail_3.jpg

Are you used to sending XMLs to Encoding.com's API? Vid.ly XMLs are a bit different. Have a look! Note the usage of the source & sourcefile tags.

<?xml version="1.0"?>
<query>
  <action>AddMedia</action>
  <userid>[User_ID]</userid>
  <userkey>[User_Key]</userkey>
  <notify>[email_or_URL]</notify>
<Source>
<SourceFile>[SourceFile1]</SourceFile>
<CDN>[CDNType]</CDN>
</Source>
</query>

All API action requests are sent to the http://m.vid.ly/api/ page. Client must send HTTP(S) POST request with single parameter named "xml". The server response is a normal XML document.  Also, an HTML form at http://m.vid.ly/test/test_api.php may be used to send a request to API.