Public json-api to interface with

1) General notes

this is all working draft and subject to changes

General Implementation Notes

implementation tries to follow mostly (but not the required mime-type) and uses CORS so you can use it cross-domain inside browser. no api-key is needed as the api just gives a json with metainformation plus the urls of the mp4 and thumbs/bigs that are public available on anyway. so the movie.* are not full resolution but 640x480 or smaller if stated below. later when a login mechanism is implemented there might be a possiblity to get also the original file (but this might be of any format mov/avi/… as it was uploaded) or maybe a fullscale converted mp4, and is accounted on the share-ratio of the user (means user needs to have reviewed uploads and good share-ratio).

License and usage agreement:

on using this api you agree on:

  1. the application using this api must be public accessible for everyone free of charge and the link needs to be submitted to so we can build up a registry of all tools using videopong. if you want to charge the users or freemium please get in contact with us first so we can discuss an exception.
  2. content must not be cached, as we need to be able to take copyright violating content offline. there might be still some situation where caching is mandatory but such cases need to be discussed with us first please:

Sample Urls inside json answers like: (big[1-3].jpg) (thumb[1-3].jpg) (gif animation of thumbs) (640x480 h264 preview) (320x240-12fps gif preview)



support to this api is possibly given via

please write your comments and ideas to this api to and maybe join discussions on the videopong users group.

2) implemented API Calls

2.1) Error Numbers

0 : ok

1 : general error: use the errorstring

2 : not logged in: use the “login” api and check with “login/ami”

3 : upload failed: show the errorstring

2.2) Stats

use this to initialize your application, get some basic information, … generic and also videopong-specific


    "status": {

            "error": 0,

            "errorstring": "ok"


    "data": {

            "service_name": "videopong",

            "service_status": "0",

            "service_news": "web api to interact with videopong for applications",

            "service_description": "footage exchange platform for (live-)videoartists",

            "url_front": "http:\/\/",

            "url_logo": "http:\/\/\/customer\/vp\/media\/logo-beta.png",

            "url_help": "http:\/\/\/static\/faq",

            "url_about": "http:\/\/\/static\/concept",

            "videopong": {

                    "total_clips": "20389",

                    "total_users": "1789"




2.3) Cliplists:                                   

returns a cliplist of: 1 testclip<number>                   

returns a cliplist of: get <number> random clips (max 50, default 1 if not specified)<clipid>                           

returns a cliplist of: 1 clip<needle>/<offset>/<number>    

returns a cliplist of: searches for <needle> and shows <number> clips starting with offset of <offset> clips

default <offset> is 0 and default <number> is 1 (maximum <number> is 50)

if you get OK with no results check your offset                          

returns a cliplist of: get a maximum of 3 last viewed clips if user has been viewing clips before on
        videopong or any js-app that uses this api
        returns a cliplist of: only own uploads (if user is logged in: otherwise error=1)

        returns a cliplist of: only own downloads (if user is logged in: otherwise error=1)<userid>/uploads

        returns a cliplist of: only uploads of user <userid>. instead of setting own userid just use “me”<userid>/downloads
        returns a cliplist of: only downloads of user <userid>. instead of setting own userid just use “me”

example answer for a cliplist (with 1 result,... the-data array would contain more when more results)


    "status": {

            "error": 0,

            "errorstring": "ok"


    "data": [


                    "id": "0cijjx237ht",

                    "title": "test file",

                     "reputation": 1,

                    "thumbs_up": 1,

                    "thumbs_down": 0,

                    "views": "281",

                    "downloads": "19",

                    "duration": "10",

                    "framerate": "25",

                    "resolution": "640x480",

                    "upload_date": "2008-05-15 14:25:53",

                    "license": "byncsa",

                    "url_thumb": "http:\/\/\/pics\/0cijjx237ht\/thumb1.jpg",

                    "url_thumb_gif": "http:\/\/\/pics\/0cijjx237ht\/thumb.gif",

                    "url_big": "http:\/\/\/pics\/0cijjx237ht\/big1.jpg",

                    "url_preview_mp4": "http:\/\/\/clip\/view\/0cijjx237ht\/movie.mp4",

                    "url_preview_gif": "http:\/\/\/clip\/view\/0cijjx237ht\/movie.gif",

                    "url_download": "http:\/\/\/clip\/download\/0cijjx237ht\/",

                    "url_videopong": "http:\/\/\/clip\/detail\/0cijjx237ht"

            }, {

                    "name": "mr.shintla",

                    "userid": "1",

                    "url_videopong": "http:\/\/\/user\/1\/mr.shintla",

                    "url_api": "http:\/\/\/api\/user\/1"



    "count": 1


if status->error is not 0:

use status->errorstring as result to the user. might contain html-tags like <a> and <img>

<count> shows always the number of total results. important for searches where results are paginagted...

2.4) User Login & Detail

use it as popup/iframe that user can authenticate themself on"", "videopong login","status=0,menubar=0,titlebar=0,toolbar=0,width=350,height=350");

        additional GET-parameters to overwrite default-colors possible:

        example: .../api/login/?colorbg=ff0000&colorfg=00ff00&colorbg2=ff00ff

attention: colors are NOT saved in a session or such, so you need to set them on each call

returns logged_in==true if a user is logged in. plus some more details


    "status": {

            "error": 0,

            "errorstring": "ok"


    "data": {

            "logged_in": true,

            "userid": "<userid>",

             "unfinished_uploads": ["0f7kgcqx2mz", "0f7nypho6py"],

            "unread_messages": 0



if “false” the userid is set to 0. please do redirect/open as popup the user to the login screen with this api call:

<userid> : integer

unfinished_uploads holds the ids of the clips that need to be finished to be public available. use the /api/clip/<clipid> to get information about this upload. or open an iframe/popup on /api/upload/finish/<clipid> to allow the user to finish his upload (see detail instructions in chapter 2.5 )<userid>/detail

        returns detail information to a user of a given userid


    "status": {

            "error": 0,

            "errorstring": "ok"


    "data": {

            "name": "mr.shintla",

            "url_videopong": "http:\/\/\/user\/1\/mr.shintla",

            "reputation": 36,

            "thumbs_up": 39,

            "thumsb_down": 3,

            "url": "http:\/\/",

            "crew_name": "bildstörung \/ videokultur",

            "crew_url": "http:\/\/",

            "social_facebook": "bildstoerung.vjs",

            "social_twitter": "videopong",

            "social_google": ""



2.5) Uploads

first you need to check if the user is logged in (see /api/login/ami)

then post your file inside POST-var “files[0]” to

answers with error = 2 mean the user is not logged in… use the api to do so

answers with error = 3 are failed uploads. show the errorstring to the user

example of html-form:

<form method="post" action="" enctype="multipart/form-data">

<input name="files[0]" type="file" />

<input type="submit" value="post clip to api" />


example of successful upload


    "status": {

            "error": 0,

            "errorstring": "ok"


    "data": {

            "id": "0f7jcmi3tod",

            "url_videopong": "http:\/\/\/clip\/detail\/0f7jcmi3tod",

            "url_edit": "http:\/\/\/api\/upload\/finish\/0f7jcmi3tod"



the clip is not published until all meta informations are entered (use url_edit from answer) :<clipid>

so open this url in an iframe/window so the user can finalize the upload… see documentation below


optionaly the user sees all unfinished uploads on and could get asked the number of unfinished uploads with /api/login/ami<clipid>

        open in a popup/iframe to let users finish their uploads. this needs to be done to get a clip public available on videopong. the list of open ids is inside the /api/login/ami in unifinished_uploads"<clipid>", "videopong upload","status=0,menubar=0,titlebar=0,toolbar=0,width=1000,height=320");

        additional GET-parameters to overwrite default-colors possible:

        example: .../api/upload/finish/<clipid>/?colorbg=ff0000&colorfg=00ff00&colorbg2=ff00ff

attention: colors are NOT saved in a session or such, so you need to set them on each call

3) Upcoming Implementations / Planned Features<clipid>/up|down

up-/down-voting for logged-in users….  (get/create/update|overwrite/add/publish/…)

people use it? maybe directly from vj-tools?<offset>/<x>            

newest <x> clips starting with offset of <offset> clips<offset>/<x>           

toprated <x> clips starting with offset of <offset> clips<offset>/<x>    

clips with lowest views: <x> clips starting with offset of <offset> clips

4) who uses it

please let me know where you use it here:

5) more ressources

some tutorials. let me know if you do something yourself:

6) more Ideas & notes


under consideration but declined:

own notes: