12seconds Api Hash

12SECONDS.TV – API DOCUMENTATION  VERSION 0.3 – FEBRUARY 24 T H , 2009   

INTRODUCTION TO THE 12SECONDS API  Our API is still a work in progress.  We don’t currently have any rate‐limiting set, but we would appreciate you limiting your non‐interactive requests  to 1 request every 60 seconds. If a user interacts with the application or you need to request a specific piece of  data, feel free to go above that limit.  If  you  notice  any  problems,  have  suggestions,  or  need  help,  please  e‐mail  our  developer  in  charge  of  the  API  –  Jacob Knobel ‐ [email protected] 

NEW IN VERSION 0.3  ƒ ƒ ƒ

Challenge API – Response now includes tags that match the current challenge question  Authentication API – The API now supports authenticated requests from users  Recording API – You can now record video via webcam, post a file, or have our system grab a file from a link to  post a video to a user’s account. 

NEW IN VERSION 0.2  ƒ ƒ ƒ ƒ

ƒ

Channel API ‐ Special case feeds for “everyone”, “featured” and the daily challenge.  Challenge API – Get the challenge question  Video API – Added support to get a video by Tiny12 key  Video XML nodes now include the following additional fields  o time_ago – displays time in the format of “X minutes/hours/days/weeks ago”  o num_views – The current view count for the video  o replies – Shows limited information about any video replies  o user field now includes a user’s location as specified in their profile and their user profile picture  o tiny12_link – Link for the shorter tiny12.tv address created automatically for each video  o thumb_path_large – Path to a larger 400x300 thumbnail  o mp4_path – Link to the MP4 version of each video  Caching – To speed up the API and improve speed and performance, the special case feeds and other high‐ usage feeds may be cached. Information is cached for a maximum of 30 seconds. You can be sure that any  request is returning up‐to‐date information from at least 30 seconds prior to the request and not any longer. 

HOW TO USE THE API 

All API calls are simple HTTP requests to our API server. You specify the command and a number of options and we  return an XML response to your query.  The API server where you should point your requests is located at: http://api.12seconds.tv  Requests normally follow this pattern /command/argument1/argument2.xml?optional_argument1=xxx  The API currently has 3 available commands – Channel, Video, and Search detailed below  You also need to specify a format you want the response in by appending the extension of the response to your  query, before the optional arguments. The default is XML and at the moment, it is the only format we support. 

EMBEDING VIDEOS  At the moment, we are allowing you to play our videos in your own player and in whatever fashion you choose  (but you must always link back to 12seconds.tv and show somehow that the clip is from 12seconds.tv). However, if  you would like to use our embeddable player, here is our embed code:  <iframe src="http://embed.12seconds.tv/i/embed?v=VIDEO_ID" scrolling="no"  allowtransparency="true" frameborder="0" width="430" height="360">
VIDEO_TITLE on 12seconds.tv   

API COMMANDS   

CHANNEL  The channel command is used to pull the basic video streams for a user. We have two main options here:  • •

User Stream – Contains all of a user’s own videos (everything you would see on a user’s channel page)  Friend Stream – Contains all video’s that were posted by the people a user is following. 

  Request: channel (username, streamtype, [limit], [includeme])  username – The username of the user. (This is NOT the userID)  streamtype – This option can either be “userstream” or “friendstream”.  limit – The maximum number of clips you want in your response. Defaults to 12. Maximum is 100.  includeme – This is only applicable for the Friend Stream. A value of “true” means that a user’s own videos will be  included in their friends feed. A value of “false” will not include a user’s own videos. Defaults to false.  Special Cases: 

We have streams available for featured content, the daily challenge, and all clips. To view these feeds, substitute  the username with either “featured”, “12challenge” or “everyone”. You must use the “friendstream” streamtype  for these special cases. The includeme property is ignored for the special case streams.  Examples:  To get the 12 most recent videos from a user with username “sol”:  http://api.12seconds.tv/channel/sol/userstream.xml?limit=12  To get the most recent videos of Sol’s friends, including his own videos:  http://api.12seconds.tv/channel/sol/friendstream.xml?includeme=true  To get the 25 most recent clips recorded by all users on the site (everyone):  http://api.12seconds.tv/channel/everyone/friendstream.xml?limit=25   

VIDEO  The video command is used to retrieve information about a specific video. A common use for this would be for a  case  where  you  want  to  retrieve  information  about  a  single  video  that  you  know  the  ID  of  or  if  you  were  monitoring an external service like twitter for 12seconds links and wanted to fetch information on the video that  was just tweeted.  Request: video (action, videoID/Tiny12key)  action – Can be “get” to return a video normally or “get_tiny12” to look up a video by it’s tiny12 key  videoID – The ID of the video. This is always an integer. (Only valid when using “get” as your action)  Tiny12key – The Tiny12 key of the video. This is a 5‐7 digit combination of letters and numbers. (Only valid when  using “get_tiny12” as your action)  Examples:  To retrieve information about a video with ID “5556”  http://api.12seconds.tv/video/get/5556.xml 

SEARCH  The search command will allow you to perform various search functions on our site and get the responses back as  XML nodes of whatever content type you are searching for. At the moment, we only support tag searching. This  tag is great if you run a site where you ask your users to tag video relating to your site with a specific name and you  want to display all matching videos on your site.  Request: search (action, searchstring, [limit], [username])  action – The only option currently is “tagsearch”  searchstring – Your search term. This is basic text search – no fancy operators. Not case sensitive.  limit – The maximum number of clips you want in your response. Defaults to 12. Maximum is 100.  username – Restrict the search to only a specific user’s videos. Defaults to all users 

Examples:  To retrieve a list of the last 25 videos matching the tag “reviews”  http://api.12seconds.tv/search/tagsearch/reviews.xml?limit=25  To retrieve a list of all videos labeled “reviews” by the user with name “reviewwebsite”:  http://api.12seconds.tv/search/tagsearch/reviews.xml?username=reviewwebsite 

CHALLENGE  The challenge API allows you to get the site’s daily challenge question  Request: getchallenge ()  There are no parameters or options for this command  Examples:  To retrieve the current challenge question on the site:  http://api.12seconds.tv/challenge/getchallenge 

AUTHENTICATION  The Authentication API allows a user to authenticate with 12seconds and perform API requests as a logged‐in user  of  the  system.  Authentication  works  using  an  initial  request  submitting  login  credentials  which  then  returns  a  session  auth  key.  That  auth  key  is  then  used  for  all  subsequent  requests  that  require  authentication.  Authentication keys last forever unless a user a) changes their password, b) removes their account or c) the logout  API function is called. Authentication keys are alphanumeric strings not to exceed 40 characters.  Authentication  requests  are  only  allowed  for  verified  API  partners.  (To  become  a  partner,  please  e‐mail  [email protected]).  Each  partner  is  given  a  partner  identifier  and  a  secret  key  used  in  their  hashing.  Authentication keys are mapped to a partner and will not work with other partnerIDs.  Whenever a password is passed, the password must be the following MD5 hash:  md5(userPassword)‐secretkey.  So,  if  the  user’s  password  was  “testPW”  and  the  secret  key  is  “x9n3njkf345”,  the  MD5  hash  would  be  MD5(MD5(“testPW”)‐ x9n3njkf345”). We need the double hash because we don’t store user’s passwords in a raw  format anywhere.  If a partnerID is invalid or the API request is otherwise inaccurate, the API will respond with an error in the format  <error code=”XX”>error_text. A list of error codes and responses will be available soon.  For all of the authentication commands, the requests should be sent has http://api.12seconds.tv/auth/command  with all the rest of variables passed in as POST vars with names set as specified in the function calls below.  verify(partner_id,username,passwordHash)  ƒ ƒ

Used to verify and validate account information. Does not generate a session key, simply confirms or denies  user credentials  Returns 1 with valid credentials, 0 on fail. 

login(partner_id,username,passwordHash)  ƒ ƒ

Used to actually login and get an authkey to be used for future requests  Returns  1  XXXXXXXXXXX  0 on fail. 

with 

valid 

credentials, 

logout(partner_id,authkey)  ƒ ƒ

Used to destroy an authkey so it is no longer usable  Returns <status>1 on success, <status>0 on failure. 

checkAuth(partner_id,authkey)  ƒ

ƒ

Validates  an  existing  authkey  to  make  sure  it  is  still  usable  and  valid. This  is  good  to  do  when  starting  up  a  program using an authkey generated from an earlier session. You can check the site to make sure the user has  not invalidated their authkey before allowing them to perform actions as if they were logged in.   Returns 1 with a valid authkey, 0 on fail.. 

RECORDING  The  Recording  API  allows  you  to  have  users  record  videos  for  12seconds.tv  remotely  from  anywhere  on  the  internet or in any internet connected program. There are three ways to submit video through the recording API –  through  webcam,  file  upload,  or  a  direct  link  to  a  hosted  file.  All  recording  requests  require  a  valid  logged‐in  authkey.  Basic Recording Workflow:  1. 2.

3. 4.

Request  is  made  to  get  a  recording  token.  Recording  tokens  last  30  minutes  and  then  expire.  You  only  have 30 minutes from the request of the token to complete the entire post process.  Token is then used to post a webcam stream, file upload, or direct link. For a webcam stream, a URL is  provided to load into your application that has a flash recorder in it. To use a webcam, your application  must have the ability to open up or embed a browser window.  Once the file has been submitted, the API lets you know if it was valid or not.  If it is valid, you can then prompt your user (or fill in yourself) for title, location, and tag information. That  information is then sent along in a second request, along with the recording token, and the information is  put together with the video submitted earlier and posted to the user’s account. The call returns the full  XML output of the newly created video. 

  Webcam Recording  ƒ Embed the following URL into your application filling in the appropriate values  http://api.12seconds.tv/i/recorder?authkey=XXXXXXXX&recordToken=XXXXXX&promptOnFinish=0&redir ect=http://yourfinishedsite.com   ƒ A recorder will load up that will allow the user to select their camera, record a 12, review their recording,  cancel their recording and start again, or approve and post the recording. The promptOnFinish and  redirect parameters are optional, the others are required.  ƒ Once the user has confirmed their recording, a number of things can happen. If you have promptOnFinish  set to “1”, we’ll alert the user that their recording has been saved and tell them to close the window – this  is best for situations where you have no control or monitoring abilities on the recording window. If you 

ƒ ƒ

application has the ability to monitor the current URL of the recorder window (such as Flex/AIR  applications), you can use the redirect parameter to direct the embedded browser to a page of your  choosing after the user has saved their post. You can then monitor for this URL in your application and  close the window when it is reached.   You then continue and prompt the user for the meta information and pass along through normal API calls.  Videos are not posted until the final postVideo API call is made with meta information. 

For all of the authentication commands, the requests should be sent has http://api.12seconds.tv/record/command  with all the rest of variables passed in as POST vars with names set as specified in the function calls below.    getToken(partner_id,authkey)  ƒ This simply returns a recording token that can be used to fetch and post a 12seconds video.  ƒ Returns XXXXXXXXX or an error. Tokens are alphanumeric and will be  under 40 characters.    uploadVideo(partner_id,authkey,recordToken,videoUpload)  ƒ Allows you to upload a file  ƒ videoUpload should be posted as a standard HTML Multi‐part Encoded form (same concept as basic file  uploads in your browser. The file object must be called ‘videoUpload’)  ƒ Returns <status>1 on success, <status>0 on failure. If there is a failure, an error code  and details will be provided in the standard error format. Errors will most likely be sent if the file was  uploaded incorrectly or if we could not convert the content requested.    directVideo(partner_id,authkey,recordToken,videoLink)  ƒ Allows you to post a video that is already available and hosted online elsewhere.   ƒ videoLink must be a full http link such as http://clips.12seconds.tv/sampleClip.mov. At the moment, we  will only be supporting fetching clips through the HTTP protocol.   ƒ Returns <status>1 on success, <status>0 on failure. If there is a failure, an error code  and details will be provided in the standard error format. Errors will most likely be sent if the file could not  be found and downloaded or if we could not convert the content requested.    postVideo(partner_id,authkey,recordToken,title,location,tags)  ƒ This completes the posting process and associates the video sent earlier with meta‐data provided by  either your application or the user via your application.  ƒ Title, Tag, and Location are all strings not to exceed 100 characters each. Tags should be provided as  comma separated list, just as they are on the normal site.   ƒ Returns <status>1 along with a full XML output of the newly created video on success (similar to  calling a Video API request on the new videoID) along with or <status>0 along with an error in  the standard format if there was an issue.