Fast and effective Instagram Private API wrapper (public+private requests and challenge resolver)
Project description
instagrapi
Fast and effective Instagram Private API wrapper (public+private requests and challenge resolver). Use the most recent version of the API from Instagram, which was obtained using reverse-engineering with Charles Proxy.
Instagram API valid for 27 September 2020 (last reverse-engineering check) Support Python>=3.6
Features
- Performs public (
_gql
or_a1
suffix methods) or private/auth (_v1
suffix methods) requests depending on the situation (to avoid Instagram limits) - Challenge Resolver have Email (as well as recipes for automating receive a code from email) and SMS handlers
- Support upload a Photo, Video, IGTV, Albums and Stories
- Support work with User, Media, Insights, Collections and Direct objects
- Insights by posts and stories
- Build stories with custom background and font animation
Install
pip install instagrapi
Tests
python -m unittest tests
python -m unittest tests.ClientPublicTestCase
Requests
Public
(anonymous) methods had suffix_gql
(InstagramGraphQL
) or_a1
(examplehttps://www.instagram.com/adw0rd/?__a=1
)Private
(authorized request) methods have_v1
suffix
The first request to fetch media/user is public
(anonymous), if instagram raise exception, then use private
(authorized).
Example (pseudo-code):
def media_info(media_pk):
try:
return self.media_info_gql(media_pk)
except ClientError as e:
# Restricted Video: This video is not available in your country.
# Or media from private account
return self.media_info_v1(media_pk)
Usage
from instagrapi import Client
cl = Client()
cl.login(ACCOUNT_USERNAME, ACCOUNT_PASSWORD)
user_id = cl.user_id_from_username("adw0rd")
medias = cl.user_medias(user_id, 20)
Account
This is your authorized account
Method | Return | Description |
---|---|---|
login(username: str, password: str, settings: dict = {}) | Bool | Login by username and password |
relogin() | Bool | Relogin with clean cookies (required cl.username/cl.password) |
login_by_sessionid(sessionid: str) | Bool | Login by sessionid from Instagram site |
get_settings() | Dict | Return settings dict (more details below) |
set_proxy(dsn: str) | Dict | Support socks and http/https proxy |
cookie_dict | Dict | Return cookies |
user_id | Int | Return you user_id (after login) |
device | Dict | Return device dict which we pass to Instagram |
set_device(device: dict) | None | Change device settings |
set_user_agent(user_agent: str) | None | Change User-Agent header |
base_headers | Dict | Base headers for Instagram |
Example:
cl.login("instagrapi", "42")
# cl.login_by_sessionid("peiWooShooghahdi2Eip7phohph0eeng")
cl.set_proxy("socks5://127.0.0.1:30235")
# cl.set_proxy("http://127.0.0.1:8080")
print(cl.get_settings())
print(cl.user_info(cl.user_id))
You can pass settings to the Client (and save cookies), it has the following format:
settings = {
"uuids": {
"phone_id": "57d64c41-a916-3fa5-bd7a-3796c1dab122",
"uuid": "8aa373c6-f316-44d7-b49e-d74563f4a8f3",
"client_session_id": "6c296d0a-3534-4dce-b5aa-a6a6ab017443",
"advertising_id": "8dc88b76-dfbc-44dc-abbc-31a6f1d54b04",
"device_id": "android-e021b636049dc0e9"
},
"cookies": {}, # set here you saved cookies
"last_login": 1596069420.0000145,
"device_settings": {
"cpu": "h1",
"dpi": "640dpi",
"model": "h1",
"device": "RS988",
"resolution": "1440x2392",
"app_version": "117.0.0.28.123",
"manufacturer": "LGE/lge",
"version_code": "168361634",
"android_release": "6.0.1",
"android_version": 23
},
"user_agent": "Instagram 117.0.0.28.123 Android (23/6.0.1; ...US; 168361634)"
}
cl = Client(username, password, settings=settings)
This values send to Instagram API.
Media
Viewing and editing publications (medias)
media_id
- String ID"{media_id}_{user_id}"
, example"2277033926878261772_1903424587"
(Instagram terminology)media_pk
- Integer ID (real media id), example2277033926878261772
(Instagram terminology)code
- Short code (slug for media), exampleBjNLpA1AhXM
from"https://www.instagram.com/p/BjNLpA1AhXM/"
url
- URL to media publication
Method | Return | Description |
---|---|---|
media_id(media_pk: int) | Str | Return media_id by media_pk |
media_pk(media_id: str) | Int | Return media_pk by media_id |
media_pk_from_code(code: str) | Int | Return media_pk |
media_pk_from_url(url: str) | Int | Return media_pk |
media_info(media_pk: int) | Dict[full media] | Return media info |
media_delete(media_pk: int) | Bool | Delete media |
media_edit(media_pk: int, caption: str) | Bool | Change caption for media |
media_user(media_pk: int) | Dict[user] | Get user info for media |
media_oembed(url: str) | Dict[short media] | Return short media info by media URL |
media_comment(media_id: str, message: str) | Bool | Write message to media |
media_comments(media_id: str) | List[comment] | Get all comments |
Example:
>>> cl.media_pk_from_code("B-fKL9qpeab")
2278584739065882267
>>> cl.media_pk_from_code("B8jnuB2HAbyc0q001y3F9CHRSoqEljK_dgkJjo0")
2243811726252050162
>>> cl.media_pk_from_url("https://www.instagram.com/p/BjNLpA1AhXM/")
1787135824035452364
>>> cl.media_oembed("https://www.instagram.com/p/B3mr1-OlWMG/")
{'version': '1.0',
'title': 'В гостях у ДК @delai_krasivo_kaifui',
'author_name': 'adw0rd',
'author_url': 'https://www.instagram.com/adw0rd',
'author_id': 1903424587,
'media_id': '2154602296692269830_1903424587',
'provider_name': 'Instagram',
'provider_url': 'https://www.instagram.com',
'type': 'rich',
'width': 658,
'height': None,
'html': '<blockquote>...',
'thumbnail_url': 'https://instagram.frix7-1.fna.fbcdn.net/v....135355164531920_1445273950655800983_n.jpg',
'thumbnail_width': 640,
'thumbnail_height': 480,
'can_view': True}
User
View a list of a user's medias, following and followers
user_id
- Integer ID of user, example1903424587
Method | Return | Description |
---|---|---|
user_medias(user_id: int, amount: int = 20) | List[media] | Get list of medias by user_id |
user_followers(user_id: int) | Dict | Get dict {user_id: user, ...} of followers users |
user_following(user_id: int) | Dict | Get dict {user_id: user, ...} of following users |
user_info(user_id: int) | Dict[user] | Get user info |
user_info_by_username(username: str) | Dict[user] | Get user info by username |
user_follow(user_id: int) | Bool | Follow user |
user_unfollow(user_id: int) | Bool | Unfollow user |
user_id_from_username(username: str) | Int | Get user_id by username |
username_from_user_id(user_id: int) | Str | Get username by user_id |
Example:
>>> cl.user_followers(cl.user_id).keys()
dict_keys([5563084402, 43848984510, 1498977320, ...])
>>> cl.user_following(cl.user_id)
{
8530598273: {
"pk": 8530598273,
"username": "dhbastards",
"full_name": "The Best DH Skaters Ever",
"is_private": False,
"profile_pic_url": "https://instagram.frix7-1.fna.fbcdn.net/v/t5...9318717440_n.jpg",
"is_verified": False
},
...
}
>>> cl.user_info_by_username('adw0rd')
{'pk': 1903424587,
'username': 'adw0rd',
'full_name': 'Mikhail Andreev',
'is_private': False,
'profile_pic_url': 'https://scontent-arn2-1.cdninstagram.com/v/t51...FB463C5',
'is_verified': False,
'media_count': 102,
'follower_count': 578,
'following_count': 529,
'biography': 'Engineer: Python, JavaScript, Erlang\n@dhbastards ...',
'external_url': 'https://adw0rd.com/',
'is_business': False}
Upload Media as Post (to Feed)
Method | Return | Description |
---|---|---|
photo_upload(path, caption) | Dict[media] | Upload photo (Support JPG files) |
photo_download(media_pk) | Str[path] | Download photo (Return path to photo with best resoluton) |
video_upload(path, caption) | Dict[media] | Upload video (Support mp4 files) |
video_download(media_pk) | Str[path] | Download video (Return path to video with best resoluton) |
igtv_upload(path, title, caption) | Dict[media] | Upload IGTV (Support mp4 files) |
igtv_download(media_pk) | Str[path] | Download IGTV (Return path to video with best resoluton) |
album_upload(paths, caption) | Dict[media] | Upload Album (Support JPG and mp4) |
album_download(media_pk) | List[path] | Download Album (Return multiple paths to photo and video with best resolutons) |
Stories
Upload medias to you stories. Common arguments:
filepath
- Path to media filecaption
- Caption for story (now use to fetch mentions)thumbnail
- Thumbnail instead capture from source fileusertags
- Specify usertags for mention users in storyconfigure_timeout
- How long to wait in seconds for a response from Instagram when publishing a storylinks
- "Swipe Up" links (now use first)
Method | Return | Description |
---|---|---|
photo_upload_to_story(filepath: str, caption: str, thumbnail: str = None, usertags: list = [], configure_timeout: int = 3, links: list = []) | Dict[media] | Upload photo (Support JPG files) |
video_upload_to_story(filepath: str, caption: str, thumbnail: str = None, usertags: list = [], configure_timeout: int = 3, links: list = []) | Dict[media] | Upload video (Support mp4 files). |
Examples:
path = cl.video_download(
cl.media_pk_from_url('https://www.instagram.com/p/CGgDsi7JQdS/')
)
cl.video_upload_to_story(
path,
"Credits @adw0rd",
usertags=[
{'user': {'pk': 1903424587, 'name': 'adw0rd'}, 'x': 0.49892962, 'y': 0.703125, 'width': 0.8333333333333334, 'height': 0.125}
],
links=[{'webUri': 'https://adw0rd.com/'}]
)
Collections
Method | Return | Description |
---|---|---|
collections() | List[collection] | Get all account collections |
collection_medias_by_name(name) | List[media] | Get medias in collection by name |
collection_medias(collection_id, amount=21, last_media_pk=0) | List[media] | Get medias in collection by collection_id; Use amount=0 to return all medias in collection; Use last_media_pk to return medias by delta |
Insights
In the process of describing
Direct
In the process of describing
Challenge
In the process of describing
Common Exceptions
Exception | Base | Description |
---|---|---|
ClientError | Exception | Base Exception for Instagram calls |
GenericRequestError | ClientError | Base Exception for Request |
ClientGraphqlError | ClientError | Exception for GraphQL calls |
ClientJSONDecodeError | ClientError | JSON Exception |
ClientConnectionError | ClientError | Connection error |
ClientBadRequestError | ClientError | HTTP 400 Exception |
ClientForbiddenError | ClientError | HTTP 403 Exception |
ClientNotFoundError | ClientError | HTTP 404 Exception |
ClientThrottledError | ClientError | HTTP 429 Exception |
ClientRequestTimeout | ClientError | Request Timeout Exception |
ClientIncompleteReadError | ClientError | Raised when response interrupted |
ClientLoginRequired | ClientError | Raised when Instagram required Login |
ReloginAttemptExceeded | ClientError | Raised when all attempts exceeded |
Private Exceptions
Exception | Base | Description |
---|---|---|
PrivateError | ClientError | Base Exception for Private calls (received from Instagram) |
FeedbackRequired | PrivateError | Raise when get message=feedback_required |
LoginRequired | PrivateError | Raise when get message=login_required |
SentryBlock | PrivateError | Raise when get message=sentry_block |
RateLimitError | PrivateError | Raise when get message=rate_limit_error |
BadPassword | PrivateError | Raise when get message=bad_password |
UnknownError | PrivateError | Raise when get unknown message (new message from instagram) |
Challenge Exceptions
Exception | Base | Description |
---|---|---|
ChallengeError | PrivateError | Base Challenge Exception (received from Instagram) |
ChallengeRedirection | ChallengeError | Raise when get type=CHALLENGE_REDIRECTION |
ChallengeRequired | ChallengeError | Raise when get message=challenge_required |
SelectContactPointRecoveryForm | ChallengeError | Raise when get challengeType=SelectContactPointRecoveryForm |
RecaptchaChallengeForm | ChallengeError | Raise when get challengeType=RecaptchaChallengeForm |
SubmitPhoneNumberForm | ChallengeError | Raise when get challengeType=SubmitPhoneNumberForm |
Media Exceptions
Exception | Base | Description |
---|---|---|
MediaError | PrivateError | Base Media Exception (received from Instagram) |
MediaNotFound | MediaError | Raise when user unavailable |
User Exceptions
Exception | Base | Description |
---|---|---|
UserError | PrivateError | Base User Exception (received from Instagram) |
UserNotFound | UserError | Raise when user unavailable |
Collection Exceptions
Exception | Base | Description |
---|---|---|
CollectionError | PrivateError | Base Collection Exception (received from Instagram) |
CollectionNotFound | CollectionError | Raise when collection unavailable |
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for instagrapi-1.1.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7b5ad407054497d2dca6a3400e66fb60fdcc3469f9cb73e7bfb414a82abd6cb3 |
|
MD5 | bed013caeb470fa3c5790ada94ce49dc |
|
BLAKE2b-256 | 2451609e04c96c4fdc08895e2c6949c7101ea0b04f0e898c30c32372b65afa8e |