Quantcast
 

yfrog API

Please request your developer key before using yfrog API.

Uploading to yfrog
Photo Count
Photo Info
User Photos
Accessing Images in Different Sizes
File Info in XML
OEMBED format
Chunked Upload API

Uploading Media Files into yfrog Account

Use this API to upload media files into yfrog account using POST.

API Syntax

http://yfrog.com/api/xauth_upload or https://yfrog.com/api/xauth_upload

Parameters

  • media -- filename required.
  • key -- your API key required.

Send all OAuth upload requests using POST to: 


    http://yfrog.com/api/xauth_upload

or


    https://yfrog.com/api/xauth_upload

X-Auth-Service-Provider: https://api.twitter.com/1/account/verify_credentials.xml (only XML is supported at this time).
You will need a header for authorization, here it is:

X-Verify-Credentials-Authorization:


    OAuth realm="http://api.twitter.com/",
    oauth_consumer_key="",
    oauth_signature_method="HMAC-SHA1",
    oauth_token="",
    oauth_timestamp="",
    oauth_nonce="",
    oauth_version="1.0",
    oauth_signature=""

Here is a sample POST from php via command line: 


    # php yfrog_test.php ./test.jpg

    [jack@zero ~]$ php yfrog_test.php ./test.jpg

    * About to connect() to yfrog.com port 80 (#0)
    *   Trying 208.94.0.29... * connected
    * Connected to yfrog.com (208.94.0.29) port 80 (#0)
    > POST /api/xauth_upload HTTP/1.1
    Host: yfrog.com
    Accept: */*
    X-Auth-Service-Provider:
    https://api.twitter.com/1/account/verify_credentials.xml
    X-Verify-Credentials-Authorization:
    oauth_consumer_key="kgmLtpVA6ipyBcePT7MKaQ",
    oauth_nonce="6c893cf4adb9f9d28aadc86b16fe837b",
    oauth_signature="U7KgIJPBtaEtRN8BfxTRFVoL9kE%3D",
    oauth_signature_method="HMAC-SHA1", oauth_timestamp="1274651607",
    oauth_token="139881639-MePpdaz3Kvz6WuOeKFeQgLOdg3f54gVMGXcQRryY",
    oauth_version="1.0"
    Content-Length: 923876
    Expect: 100-continue
    Content-Type: multipart/form-data;
    boundary=----------------------------a21ff70823f9
    * Closing connection #0

    Response is:

    <?xml version="1.0" encoding="UTF-8"?>
    <rsp stat="ok">
    <mediaid>af11zj</mediaid>
    <mediaurl>http://yfrog.com/af11zj</mediaurl>
    </rsp>

See working example (PHP) here: http://imageshackapi.googlecode.com/files/upload-to-yfrog-example-with-xauth.php

↑ top

Photo Count

This API returns the count of the photos uploaded by a user.

API Syntax

http://yfrog.com/api/photocount.json?devkey=YOUR_KEY_HERE&screen_name=screen_name

Pareameters

  • devkey -- your developer key.
  • screen_name -- the screen name of the user whose photo count to retrieve.

Response

Here is a sample call to the API and the JSON response: 


    http://yfrog.com/api/photocount.json?devkey=YOUR_KEY_HERE&screen_name=yfmikhail
    	                        


    {
       "result":{
          "count":452
       },
       "meta":[

       ],
       "success":true,
       "error":null
    }
↑ top

Photo Info

Use this API to retrieve information related to the given photo.

API Syntax

http://yfrog.com/api/photoinfo.json?devkey=YOUR_KEY_HERE&url=HASH

Parameters

  • devkey -- your developer key.
  • url -- the hash of a photo in question, e.g. yfrog.com/HASH.

Response

Here is a sample call to the API and the JSON response: 


    http://yfrog.com/api/photoinfo.json?devkey=YOUR_KEY_HERE&url=gya022j
                                


    {
       "result":{
          "photo_info":[
             {
                "created_time":"1305959335",
                "time_ago":"4 months, 1 week",
                "message":" "A Starry Night of Iceland" from #nasa \nCredit: Stephane Vetter"
             }
          ]
       },
       "meta":{
          "count":1
       },
       "success":true,
       "error":null
    }
↑ top

User Photos

This API returns all the photos uploaded by the user.

API Syntax

http://yfrog.com/api/userphotos.json?limit=5&screen_name=screen_name&page=1&devkey=YOUR_KEY_HERE

Parameters

  • limit -- how many images you want to fetch (maximum of 25 images per request).
  • page -- page number.
  • screen_name -- screen name of the user whose images to retrieve.
  • devkey -- your developer key.

Response

Here is a sample call to the API and the JSON response: 


    http://yfrog.com/api/userphotos.json?limit=5&screen_name=yfmikhail&page=1&devkey=YOUR_KEY_HERE
                            	


    {
       "result":{
          "photos":[
             {
                "photo_author":"yfmikhail",
                "photo_link":"http:\/\/yfrog.com\/kfae65j",
                "photo_info":"http:\/\/yfrog.com\/api\/photoinfo.json?url=kfae65j",
                "photo_thumb":"http:\/\/yfrog.com\/kfae65j:small",
                "photo_height":"768",
                "photo_width":"1024"
             },
             {
                "photo_author":"yfmikhail",
                "photo_link":"http:\/\/yfrog.com\/kl6t11j",
                "photo_info":"http:\/\/yfrog.com\/api\/photoinfo.json?url=kl6t11j",
                "photo_thumb":"http:\/\/yfrog.com\/kl6t11j:small",
                "photo_height":"768",
                "photo_width":"1024"
             },
             {
                "photo_author":"yfmikhail",
                "photo_link":"http:\/\/yfrog.com\/kjja6p",
                "photo_info":"http:\/\/yfrog.com\/api\/photoinfo.json?url=kjja6p",
                "photo_thumb":"http:\/\/yfrog.com\/kjja6p:small",
                "photo_height":"371",
                "photo_width":"520"
             },
             {
                "photo_author":"yfmikhail",
                "photo_link":"http:\/\/yfrog.com\/h3fjr8p",
                "photo_info":"http:\/\/yfrog.com\/api\/photoinfo.json?url=h3fjr8p",
                "photo_thumb":"http:\/\/yfrog.com\/h3fjr8p:small",
                "photo_height":"196",
                "photo_width":"440"
             },
             {
                "photo_author":"yfmikhail",
                "photo_link":"http:\/\/yfrog.com\/g0g81p",
                "photo_info":"http:\/\/yfrog.com\/api\/photoinfo.json?url=g0g81p",
                "photo_thumb":"http:\/\/yfrog.com\/g0g81p:small",
                "photo_height":"211",
                "photo_width":"654"
             }
          ]
       },
       "meta":{
          "pagination":{
             "total":null,
             "offset":0,
             "limit":5,
             "page":1
          }
       },
       "success":true,
       "error":null
    }
↑ top

Accessing Images in Different Sizes

Photos uploaded to yfrog.com can be retrieved in certain pre-defined sizes by appending a suffix parameter to the photo’s landing page URL. The following table shows the currently available sizes and the API suffix associated with each size.

API Syntax

http://yfrog.com/hash:parameter

Parameters

Parameter Resolution Supported Media
small 100x100 photos and videos
iphone 480x480 photos and videos
medium 640x480 photos
frame First frame of a video file videos

Response

The file in the selected resolution. For example:


    http://yfrog.com/kfae65j:small
    http://yfrog.com/kfae65j:iphone
    http://yfrog.com/kfae65j:medium
    http://yfrog.com/jlvd1z:frame
↑ top

File Info in XML Format

Use this API to retrieve information about a file.

API Syntax

http://yfrog.com/api/xmlInfo?path=hash

Parameters

  • path -- the hash of a photo in question, e.g, yfrog.com/hash.

Response

Here is an example of XML returned by the following call: 


    http://yfrog.com/api/xmlInfo?path=0g6i6xv3j
                            

    <?xml version="1.0" encoding="iso-8859-1"?>
    <imginfo xmlns="http://ns.imageshack.us/imginfo/6/" version="6" timestamp="1234911746">
            <rating>
                    <ratings>0</ratings>
                    <avg>0.0</avg>
            </rating>
            <files server="16" bucket="733">
                    <image size="189113" content-type="image/jpeg">6i6xv3.jpg</image>
                <thumb size="5889" content-type="image/jpeg">6i6xv3.th.jpg</thumb>
            </files>
            <resolution>
                <width>410</width>
                <height>500</height>
            </resolution>
            <class>r</class>
            <uploader>
            </uploader>
            <links>
                <image_link>http://img16.imageshack.us/img16/733/6i6xv3.jpg</image_link>
                <image_html><a href="http://img16.imageshack.us/my.php?image=6i6xv3.jpg" target="_blank"><img
                src="http://img16.imageshack.us/img16/733/6i6xv3.jpg" alt="Free Image Hosting at www.ImageShack.us"
                border="0"/></a></image_html>
                <image_bb>[URL=http://img16.imageshack.us/my.php?image=6i6xv3.jpg]
                [IMG]http://img16.imageshack.us/img16/733/6i6xv3.jpg[/IMG][/URL]</image_bb>
                <image_bb2>[url=http://img16.imageshack.us/my.php?image=6i6xv3.jpg]
                [img=http://img16.imageshack.us/img16/733/6i6xv3.jpg][/url]</image_bb2>
                <thumb_link>http://img16.imageshack.us/img16/733/6i6xv3.th.jpg</thumb_link>
                <thumb_html><a href="http://img16.imageshack.us/my.php?image=6i6xv3.jpg" target="_blank">
                <img src="http://img16.imageshack.us/img16/733/6i6xv3.th.jpg"
                                    alt="Free Image Hosting at www.ImageShack.us"
                border="0"/></a></thumb_html>
                <thumb_bb>[URL=http://img16.imageshack.us/my.php?image=6i6xv3.jpg]
                [IMG]http://img16.imageshack.us/img16/733/6i6xv3.th.jpg[/IMG][/URL]</thumb_bb>
                <thumb_bb2>[url=http://img16.imageshack.us/my.php?image=6i6xv3.jpg]
                [img=http://img16.imageshack.us/img16/733/6i6xv3.th.jpg][/url]</thumb_bb2>
                <ad_link>http://img16.imageshack.us/my.php?image=6i6xv3.jpg</ad_link>
                <done_page>http://img16.imageshack.us/content.php?page=done&l=img16/733/6i6xv3.jpg</done_page>
            </links>
    </imginfo>

For video files result is XML document like this:


    <?xml version="1.0" encoding="ISO-8859-1"?>
    <imginfo xmlns="http://ns.imageshack.us/imginfo/7/" version="7" timestamp="1243036600">
            <rating>
            <ratings>0</ratings>
            <avg>0.0</avg>
            </rating>
            <files server="190" bucket="6189">
            <image size="197679" content-type="video/mp4">samplew.mp4</image>
            <thumb size="1258" content-type="image/jpeg">samplew.mp4.th.jpg</thumb>
            <frame size="6523" content-type="image/jpeg">samplew.mp4.frm.jpg</frame>
            </files>
            <resolution>
            <width>480</width>
            <height>318</height>
            </resolution>
            <video-info>
            <status>complete</status>
            <duration>4000</duration>
        </video-info>
            <class>r</class>
            <visibility>no</visibility>
            <uploader>
            <ip>77.122.5.235</ip>
            </uploader>
            <links>
            <image_link>http://img190.imageshack.us/img190/6189/samplew.mp4</image_link>
            <thumb_link>http://img190.imageshack.us/img190/6189/samplew.mp4.th.jpg</thumb_link>
            <thumb_html><a href="http://img190.imageshack.us/my.php?image=samplew.mp4" target="_blank">
                    <img src="http://img190.imageshack.us/img190/6189/samplew.mp4.th.jpg"
                    alt="Free Image Hosting at www.ImageShack.us" border="0"/></a></thumb_html>
            <thumb_bb>[URL=http://img190.imageshack.us/my.php?image=samplew.mp4]
                    [IMG]http://img190.imageshack.us/img190/6189/samplew.mp4.th.jpg[/IMG][/URL]</thumb_bb>
            <thumb_bb2>[url=http://img190.imageshack.us/my.php?image=samplew.mp4]
                    [img=http://img190.imageshack.us/img190/6189/samplew.mp4.th.jpg][/url]</thumb_bb2>
            <video_embed><embed src="http://img190.imageshack.us/flvplayer.swf?f=Psamplew" width="480" height="338"
                    allowFullScreen="true" type="application/x-shockwave-flash"/>
                    </video_embed>
            <ad_link>http://img190.imageshack.us/my.php?image=samplew.mp4</ad_link>
            <done_page>http://img190.imageshack.us/content.php?page=done&l=img190/6189/samplew.mp4</done_page>
            </links>
    </imginfo>

For example, if thumbnail image is present, "thumb_link" (sub-element of "links") element will contain URL of thumbnail image.

In case of an error the document with the root element "links" and the element "error" present will be returned. The "error" element may contain human-readable error message.

Example:


    <links>
            <error>no such file</error>
    </links>

Note: this API may return HTTP redirect code which must be honored by HTTP client.

↑ top

OEMBED Format

Use this API to retrieve images in OEMBED format. OEMBED is an embeddable representation of media usually sent in JSON or XML format. Please see http://www.oembed.com/ for details on the standard. With an OEMBED response, a website can display an image or a video without having to deal with the media resource directly to know how to display it.

API Syntax

http://www.yfrog.com/api/oembed?url=http:\/\/yfrog.com/hash

Parameters

  • url -- the yfrog URL.

Response

Here is a sample call to the API and the JSON response: 


    http://www.yfrog.com/api/oembed?url=http:\/\/yfrog.com/2pswonj (escaped version)
    http://www.yfrog.com/api/oembed?url=http%3A%2F%2Fyfrog.com%2F2pswonj (encoded version)
	                        


    {
        "version":"1.0",
        "provider_name":"yFrog",
        "provider_url":"http:\/\/yfrog.com",
        "thumbnail_url":"http:\/\/yfrog.com\/2pswonj:small",
        "width":525,
        "height":700,
        "author_url":"http:\/\/yfrog.com\/froggy.php?username=extrabaggs",
        "title":"Yfrog Image : yfrog.com\/2pswonj",
        "type":"image",
        "url":"http:\/\/img97.yfrog.com\/img97\/1103\/swon.jpg"
    }

The OEMBED response works for both photos and videos uploaded on YFrog. The response for a video request will be: 


    {
        "version":"1.0",
        "provider_name":"yFrog",
        "provider_url":"http:\/\/yfrog.com",
        "thumbnail_url":"http:\/\/yfrog.com\/ehvid00001jz:small",
        "width":640,"height":360,
        "author_url":"http:\/\/yfrog.com\/froggy.php?username=sk_tester",
        "title":"Yfrog Image : yfrog.com\/ehvid00001jz",
        "type":"video",
        "html":"http:\/\/yfrog.com\/ehvid00001jz:embed"
    }
↑ top

Chunked Upload API

Summary

The chunked upload API allows you to upload big video or image files with the ability to suspend transfers and survive any network errors. The API is using standard HTTP protocol and should work with most HTTP stack libraries. With this API, users have the flexibility of either uploading the whole media file in a single HTTP request or with multiple HTTP requests. If some of the upload requests fail, partial data is saved, and the upload could be resumed from the last saved position.

API Methods

Chunked upload API provides 3 methods:

  • start: Initiate upload, passing file metadata like tags, user information (but not actual file content)
  • put: Upload actual data. Data could be uploaded starting from certain position.
  • getlength: Allows to get uploaded data size.

Upload Process

  • Pass metadata information to server, retrieve upload URL (start method, POST)
  • Upload File data in chunks using put (PUT) method. If the upload was interrupted by network error you can use getlength (GET) method to find out how much data have been saved on server and resume from this point.

Initiating Upload

Each upload should start with POST call to
URL: http://render.imageshack.us/renderapi/start
Content-type: multipart/form-data
Method: POST

Parameters

  • filename -- name of file to be uploaded, optional. Used to determine target file name, if not specified, media file ....mp4 will be used as destination file name.
  • key -- your ImageShack API developer key.
  • cookie -- user's cookies, optional. If specified, media file will be linked to user's account.
  • tags -- comma separated list of tags, optional. Could also include geo tags.
  • username -- Imageshack user's name, optional.
  • password -- Imageshack user's password, optional.
  • t_username -- Twitter user's name, optional.
  • t_password -- Twitter user's password, optional.
  • t_verify_url -- Signed URL that points to Twitter's verify_credentials.xml.
  • content_type -- content type of uploaded file, optional. If not specified then we are trying to guess content type based on file extension. If content_type is identified as one of :
    • image/jpeg
    • image/png
    • image/gif
    • image/bmp
    • image/tiff
    • application/pdf
    then file will be uploaded and proceed as image; otherwise file will be treated as video file.

The server will respond with XML document.

Sample server response text:


    <?xml version="1.0" encoding="UTF-8"?>
    <uploadInfo
        link="http://yfrog.us/65huxz"
        putURL ="http://img676.imageshack.us/renderapi/put/b21765e5"
        getlengthURL ="http://img676.imageshack.us/renderapi/getlength/b21765e5"
    />

where:

  • putURL -- URL which should be used to upload file data.
  • getlengthURL -- URL which should be used to query current file size.
  • link -- link to uploaded file page (HTML) hosted at ImageShack.

How authentication with Twitter credentials work?

If you supplied t_username and t_password then we will contact Twitter in order to check your credentials. If the check was successful we will continue with the upload.

If you supplied t_username and t_verify_url then we will check if the information returned by Twitter using signed URL matches the expected one. If the check was successful we will continue with the upload.

If authentication with Twitter failed, a 401 HTTP error will be returned.

Uploading Data

Every time you need to upload a block of file you should perform a PUT call to putURL (as retrieved in previous stage). The URL may contain query string.

When uploading partial content, use HTTP 1.1 Content-Range headers. 


    Content-Length: 203873
    Content-Range: bytes 0-256/203873

In this example we are sending the first 257 bytes of a file with total size of 203873.

After each successful chunk upload a "202 Accepted" is returned. "201 Created" will be returned after the last block is uploaded.

Sample server 201 response text for an image: 


    <?xml version="1.0" encoding="iso-8859-1"?><imginfo xmlns="http://ns.imageshack.us/imginfo/7/" version="7"
                            timestamp="1266245431">
        <rating>
            <ratings>0</ratings>
            <avg>0.0</avg>
        </rating>
        <files server="714" bucket="6510">
            <image size="122" content-type="image/gif">imageaz.gif</image>
        </files>
        <resolution>
            <width>12</width>
            <height>21</height>
        </resolution>
        <class>r</class>
        <visibility>yes</visibility>
        <uploader>
            <ip>99.132.34.183</ip>
            <cookie>444445415b312c66ae0b4c9fe6dc47f2</cookie>
        </uploader>
        <links>
            <image_link>http://img714.imageshack.us/img714/6510/imageaz.gif</image_link>
            <image_html><a href="http://img714.imageshack.us/my.php?image=imageaz.gif"
                            target="_blank"><
                            img src="http://img714.imageshack.us/img714/6510/imageaz.gif"
                            alt="Free Image Hosting at www.ImageShack.us"
                            border="0"/></a></image_html>
            <image_bb>[URL=http://img714.imageshack.us/my.php?image=imageaz.gif]
                            [IMG]http://img714.imageshack.us/img714/6510/imageaz.gif[/IMG][/URL]</image_bb>
            <image_bb2>[url=http://img714.imageshack.us/my.php?image=imageaz.gif]
                            [img=http://img714.imageshack.us/img714/6510/imageaz.gif][/url]</image_bb2>
            <thumb_html><a href="http://img714.imageshack.us/my.php?image=imageaz.gif"
                            target="_blank"><img src="
                            http://www.imageshack.us/thumbnail.png"
                            alt="Free Image Hosting at www.ImageShack.us"
                            border="0"/></a></thumb_html>
            <thumb_bb>[URL=http://img714.imageshack.us/my.php?image=imageaz.gif]
                            [IMG]http://www.imageshack.us/thumbnail.png[/IMG][/URL]</thumb_bb>
            <thumb_bb2>[url=http://img714.imageshack.us/my.php?image=imageaz.gif]
                            [img=http://www.imageshack.us/thumbnail.png][/url]</thumb_bb2>
            <yfrog_link>http://yfrog.com/juimageazg</yfrog_link>
            <yfrog_thumb>http://yfrog.com/juimageazg.th.jpg</yfrog_thumb>
            <ad_link>http://img714.imageshack.us/my.php?image=imageaz.gif</ad_link>
            <done_page>http://img714.imageshack.us/content.php?page=done&
                            l=img714/6510/imageaz.gif</done_page>
        </links>
    </imginfo>

Sample server 201 response text for video:


    <imginfo xmlns="http://ns.imageshack.us/imginfo/7/" version="7" timestamp="1253212661">
        <rating>
            <ratings>0</ratings>
            <avg>0.0</avg>
        </rating>
        <files server="11" bucket="8175">
            <image size="0" content-type="video/mp4">samplep.mp4</image>
        </files>
        <resolution>
            <width>0</width>
            <height>0</height>
        </resolution>
        <video-info>
            <status>queued</status>
            <duration>0</duration>
        </video-info>
        <class>r</class>
        <visibility>yes</visibility>
        <uploader>
            <ip>99.132.34.183</ip>
            <cookie>444445415b312c66ae0b4c9fe6dc47f2</cookie>
        </uploader>
        <links>
            <image_link>http://img11.imageshack.us/img11/8175/samplep.mp4</image_link>
            <thumb_html><a href="http://img11.imageshack.us/my.php?image=samplep.mp4"
                            target="_blank"><
                            img src="http://img11.imageshack.us/img11/8175/samplep.mp4.th.jpg"
                            alt="Free Image Hosting at www.ImageShack.us"
                            border="0"/></a></thumb_html>
            <thumb_bb>[URL=http://img11.imageshack.us/my.php?image=samplep.mp4]
                            [IMG]http://img11.imageshack.us/img11/8175/samplep.mp4.th.jpg
                            [/IMG][/URL]</thumb_bb>
            <thumb_bb2>[url=http://img11.imageshack.us/my.php?image=samplep.mp4]
                            [img=http://img11.imageshack.us/img11/8175/samplep.mp4.th.jpg]
                            [/url]</thumb_bb2>
            <yfrog_link>http://yfrog.us/0bsamplepz</yfrog_link>
            <yfrog_thumb>http://yfrog.us/0bsamplepz.th.jpg</yfrog_thumb>
            <frame_link>http://img11.imageshack.us/img11/8175/samplep.mp4.frm.jpg</frame_link>
            <frame_html><a href="http://img11.imageshack.us/my.php?image=samplep.mp4"
                            target="_blank"><
                            img src="http://img11.imageshack.us/img11/8175/samplep.mp4.frm.jpg"
                            alt="Free Image Hosting at www.ImageShack.us"
                            border="0"/></a></frame_html>
            <frame_bb>[URL=http://img11.imageshack.us/my.php?image=samplep.mp4]
                            [IMG]http://img11.imageshack.us/img11/8175/samplep.mp4.frm.jpg[/IMG][/URL]<
                            /frame_bb>
            <frame_bb2>[url=http://img11.imageshack.us/my.php?image=samplep.mp4]
                            [img=http://img11.imageshack.us/img11/8175/samplep.mp4.frm.jpg][/url]</frame_bb2>
            <video_embed><embed src="http://img11.imageshack.us/flvplayer.swf?f=Msamplep"
                            width="640" height="380" allowFullScreen="true"
                            wmode="transparent" type="application/x-shockwave-flash"/>
                </video_embed>
            <ad_link>http://img11.imageshack.us/my.php?image=samplep.mp4</ad_link>
            <done_page>http://img11.imageshack.us/content.php?page=done&l=img11/8175/samplep.mp4<
                            /done_page>
        </links>
    </imginfo>

If your upload fails:

Server will return xml:


    <error code="CODE">MESSAGE</error>

Possible HTTP error codes:

  • 404 Not Found - URL you are requesting is not found or command is not recognized.
  • 405 Method Not Allowed - Method you are calling is not supported.
  • 400 Bad Request - Your request is bad formed, for example: missing or wrong UUID, invalid content-length.
  • 403 Forbidden - Wrong developer key.

↑ top