A Python client for the Imgur API. Also includes a friendly demo application. It can be used to interact with the Imgur API and examine its responses, as a command line utility, and it can be used as a library within your projects.
You must register your client with the Imgur API, and provide the Client-ID to make any request to the API (see the Authentication note). If you want to perform actions on accounts, the user will have to authorize your application through OAuth2.
Our developer documentation can be found here.
The best way to reach out to Imgur for API support would be our Google Group, Twitter, or via api@imgur.com.
pip install imgurpython
Using imgurpython in your application takes just a couple quick steps.
To use the client from a strictly anonymous context (no actions on behalf of a user)
from imgurpython import ImgurClient
client_id = 'YOUR CLIENT ID'
client_secret = 'YOUR CLIENT SECRET'
client = ImgurClient(client_id, client_secret)
# Example request
items = client.gallery()
for item in items
print(item.link)To initialize a client that takes actions on behalf of a user
from imgurpython import ImgurClient
client_id = 'YOUR CLIENT ID'
client_secret = 'YOUR CLIENT SECRET'
client = ImgurClient(client_id, client_secret)
# Authorization flow, pin example (see docs for other auth types)
authorization_url = client.get_auth_url('pin')
# ... redirect user to `authorization_url`, obtain pin (or code or token) ...
credentials = client.authorize('PIN OBTAINED FROM AUTHORIZATION', 'pin')
client.set_user_auth(credentials['access_token'], credentials['refresh_token'])or if you already have an access/refresh token pair you can simply do
from imgurpython import ImgurClient
# If you already have an access/refresh pair in hand
client_id = 'YOUR CLIENT ID'
client_secret = 'YOUR CLIENT SECRET'
access_token = 'USER ACCESS TOKEN'
refresh_token = 'USER REFRESH TOKEN'
# Note since access tokens expire after an hour, only the refresh token is required (library handles autorefresh)
client = ImgurClient(client_id, client_secret, access_token, refresh_token)Error types
- ImgurClientError - General error handler, access message and status code via
try
...
except ImgurClientError as e
print e.error_message
print e.status_code- ImgurClientRateLimitError - Rate limit error
get_account(username)get_gallery_favorites(username)get_account_favorites(username)get_account_submissions(username, page=0)get_account_settings(username)change_account_settings(username, fields)get_email_verification_status(username)send_verification_email(username)get_account_albums(username, page=0)get_account_album_ids(username, page=0)get_account_album_count(username)get_account_comments(username, sort='newest', page=0)get_account_comment_ids(username, sort='newest', page=0)get_account_comment_count(username)get_account_images(username, page=0)get_account_image_ids(username, page=0)get_account_album_count(username)
get_album(album_id)get_album_images(album_id)create_album(fields)update_album(album_id, fields)album_delete(album_id)album_favorite(album_id)album_set_images(album_id, ids)album_add_images(album_id, ids)album_remove_images(album_id, ids)
get_comment(comment_id)delete_comment(comment_id)create_album(fields)get_comment_replies(comment_id)post_comment_reply(comment_id, image_id, comment)comment_vote(comment_id, vote='up')comment_report(comment_id)
get_custom_gallery(gallery_id, sort='viral', window='week', page=0)get_user_galleries()create_custom_gallery(name, tags=None)custom_gallery_update(gallery_id, name)custom_gallery_add_tags(gallery_id, tags)custom_gallery_remove_tags(gallery_id, tags)custom_gallery_delete(gallery_id)filtered_out_tags()block_tag(tag)unblock_tag(tag)
gallery(section='hot', sort='viral', page=0, window='day', show_viral=True)memes_subgallery(sort='viral', page=0, window='week')memes_subgallery_image(item_id)subreddit_gallery(subreddit, sort='time', window='week', page=0)subreddit_image(subreddit, image_id)gallery_tag(tag, sort='viral', page=0, window='week')gallery_tag_image(tag, item_id)gallery_item_tags(item_id)gallery_tag_vote(item_id, tag, vote)gallery_search(q, advanced=None, sort='time', window='all', page=0)gallery_random(page=0)share_on_imgur(item_id, title, terms=1)remove_from_gallery(item_id)gallery_item(item_id)report_gallery_item(item_id)gallery_item_vote(item_id, vote='up')gallery_item_comments(item_id, sort='best')gallery_comment(item_id, comment)gallery_comment_ids(item_id)gallery_comment_count(item_id)
get_image(image_id)upload_from_path(path, config=None, anon=True)upload_from_url(url, config=None, anon=True)delete_image(image_id)favorite_image(image_id)
conversation_list()get_conversation(conversation_id, page=1, offset=0)create_message(recipient, body)delete_conversation(conversation_id)report_sender(username)block_sender(username)
get_notifications(new=True)get_notification(notification_id)mark_notifications_as_read(notification_ids)
default_memes()
Configuration is done through the config.json (placed in imgur-python/data) file in JSON format. The contents of the file should be a JSON
object with the following properties:
Key: 'client_id'
Type: string [16 characters]
Description: The Client-ID you got when you registered. Required for any API call.
Key: 'secret'
Type: string [40 characters]
Description: The client secret you got when you registered, needed fo OAuth2 authentication.
Key: 'token_store'
Type: object
Description: Future configuration to control where the tokens are stored for persistent insecure storage of refresh tokens.
Usage: python main.py (action) [options...]
credits View the rate limit information for this client
authorize Start the authorization process
authorize [pin] Get an access token after starting authorization
refresh [refresh-token] Return a new OAuth access token after it's expired
upload [file] Anonymously upload a file
list-comments [hash] Get the comments (raw JSON) for a gallery post
get-album [id] Get information (raw JSON) about an album
get-comment [id] Get a particular comment (raw JSON) for a gallery comment
get-gallery [hash] Get information (raw JSON) about a gallery post
upload-auth [access-token] [file] Upload a file to your account
comment [access-token] [hash] [text] Comment on a gallery post
vote-gallery [token] [hash] [direction] Vote on a gallery post. Direction can be either 'up', 'down', or 'veto'
vote-comment [token] [id] [direction] Vote on a gallery comment. Direction can be either 'up', 'down', or 'veto'