The Application Programming Interface
pic.im has an application programming interface so you can indeed upload photos to pic.im from any software other than our website. The pic.im API is integrated within the well-tested tr.im API, using its API rate-limiting system, error codes and account authentication system. We include the pic.im methods here for your reference, but please refer to the tr.im API for information on API keys, rate lmits, and error codes.
Authentication
Accounts at tr.im and accounts at pic.im exist with the same authentication system. They are essentially the same. So you can use any account that works at tr.im with these pic.im API methods.
pic.im Thumbnails
Thumbnail versions of all pic.im URLs are available for your use at a known URL. For example, if your pic.im URL is http://pic.im/pX, the thumbnail URL is http://pic.im/website/thumbnail/pX. You can subsitute the "pX" for any pic.im URL's unique path to get its thumbnail image for inline presentatin or other purposes.
pic.im Upload and Sharing Process via the API
Uploading a photo to pic.im for your users is a three step process: 1) you upload a photo to pic.im to get a URL for it; 2) you send the tweet directly to Twitter for your user; and 3) you send us a copy of the tweet and its related information so that we can display it right away on the pic.im viewing page with the image.
This has a number of advantages. First, we do not need to see the user's Twitter password and send the tweet for them, and you do not need to transfer this password to us in the clear. You can keep that information secure and unknown to us, if you have it. Secondly, you submit the status update with your software and take credit for it on Twitter. And most importantly, it supports OAuth from beginning to end. You can submit the tweet with the photo's URL on the user's behalf with an OAuth authorization, and then simply send us a copy of it. No one needs to see the Twitter user's password. No other social network-focused photo sharing website offers this end-to-end process, that we are aware of.
picim_url
This method is for creating pic.im URLs by uploading an image and geting a unique pic.im URL for it. You can send additional configuration options, and attach it to an authenticated tr.im account. An API key is required to use this API method.
URL:
http://api.tr.im/v1/picim_url.<format>
Method:
GET or POST
Formats:
xml, json
Parameters:
| media | Required | The binary image data to be processed and presented at the pic.im URL. |
| api_key | Optional | An application API key assigned to your application. |
| username | Optional | A tr.im username that you would like to attach the URL to. |
| password | Optional | The password for the tr.im username referenced above. |
Response:
| status | The result state, tr.im response code, and a human readable message. |
| url | A unique tr.im URL for the submitted destination URL. |
| picimpath | The pic.im URL's path string. |
| reference | A unique string generated for each pic.im URL for use with other API methods. We recommend that you save this reference code for use with future pic.im API methods. |
Notes:
- If the username and password submitted with the request do not match a valid tr.im account the upload will be rejected, and a URL will not be created. However, a username and password are not required; this only applies if you attempt to authenticate the request. All users accounts for any tr.im service exist within the same tr.im authentication system. A tr.im account is a pic.im account, and a pic.im account is a tr.im account.
- Only images of the formats JPEG, GIF, or PNG are permitted.
picim_tweet
This method is for application software to send pic.im a copy of the tweet message with the pic.im that was submitted to the social network on behalf of the user. An API key is required to use this API method.
This two step process with picim_url and picim_tweet means that we do not need to see the user's social network password to complete the photo uploading sharing process. This also allows application developers to submit the tweet message with share photos directly to the social network, and be attributed credit for it there.
URL:
http://api.tr.im/v1/picim_tweet.<format>
Method:
GET or POST
Formats:
xml, json
Parameters:
| reference | Required | The pic.im URL's unique reference string assigned at the time of it's creation. |
| tweet | Required | The tweet text as submitted to the social network, to display with the image on pic.im. |
| tweet_id | Required | The unique integer ID for the tweet, as assigned by the social network it was submitted to. |
| network | Required | The network, by name, the tweet was submitted to. Only "twitter" is a valid network, currently, but we expect to add others in the future. |
| username | Required | The social network username that tweet text was submitted to the social network for. NOT the pic.im username. |
| api_key | Required | An application API key assigned to your application. |
Response:
| status | The result state, tr.im response code, and a human readable message. |
picim_timeline
API method to get a public timeline of pic.im URLs based on a combination of time and popularity. Only pic.im URLs with attached tweet messages are included. An API key is required to use this API method.
URL:
http://api.tr.im/v1/picim_timeline.<format>
Method:
GET or POST
Formats:
xml, json
Parameters:
| api_key | Required | An application API key assigned to your application. |
| count | Optional | An integer value, the number of pic.im URLs. Defaults to 20 if not present. A maximum of 100 is permitted. |
Response:
| status | The result state, tr.im response code, and a human readable message. |
| picims | A list of the returned pic.im URLs and their individual visitation counts, with the date, time, and country for each visit. |
| picims_count | The number of pic.im URLs returned. |