yfrog API
Please request your developer key before using yfrog 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
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
}
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
}
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
}
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
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.
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"
}
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
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.