Skip to content

aiograpi

We recommend using our services:

Package PyPI PyPI - Python Version

Asynchronous Instagram Private API wrapper without selenium. Use the most recent version of the API from Instagram, which was obtained using reverse-engineering with Charles Proxy and Proxyman.

Support Python >= 3.10

Video uploads can use a built-in MP4 metadata parser when you provide thumbnail=.... Automatic thumbnail generation, StoryBuilder, and video/audio composition still need the optional video dependencies, MoviePy 2.2.1, and executable ffmpeg:

pip install "aiograpi[video]"
pip install --no-deps "moviepy==2.2.1"

MoviePy 2.2.1 currently declares Pillow<12, but aiograpi keeps Pillow>=12.2.0 for security fixes; the --no-deps install keeps the safe Pillow version. If your project imports MoviePy directly, migrate any MoviePy 1.x code from moviepy.editor, set_*, resize, and subclip APIs to the MoviePy 2.x API before upgrading.

Android users should see Pydroid and ffmpeg and Termux.

For any other languages (e.g. C++, C#, F#, D, Golang, Erlang, Elixir, Nim, Haskell, Lisp, Closure, Julia, R, Java, Kotlin, Scala, OCaml, JavaScript, Crystal, Ruby, Rust, Swift, Objective-C, Visual Basic, .NET, Pascal, Perl, Lua, PHP and others), I suggest using instagrapi-rest

Support Chat in Telegram and GitHub Discussions

Features

  1. Performs Public API (web, anonymous) or Private API (mobile app, authorized) requests depending on the situation (to avoid Instagram limits)
  2. Login by username and password, including 2FA, 8-digit backup codes, Bloks 2FA fallback/helpers, and by sessionid
  3. Challenge Resolver have Email and SMS handlers
  4. Support upload a Photo, Video, IGTV, Reels, Albums, Stories and Trial Reels
  5. Support work with User, Media, Comment, Insights, Collections, Location (Place), Hashtag and Direct Message objects
  6. Like, Follow, Edit account (Bio) and much more else
  7. Insights by account, posts and stories
  8. Build stories with custom background, font animation, link sticker and mention users
  9. Realtime MQTT for Direct message sync, lightweight Direct MQTT actions, and FBNS push notifications
  10. Account registration helpers and opt-in captcha handler hooks

Example

Realtime MQTT and Direct

aiograpi 1.3.0 continues through instagrapi 2.9.0, including experimental modern CAA email signup via signup_caa_email(...) and the graphql_www Bloks app wrapper. aiograpi 1.2.x includes the MQTT/FBNS helpers from 1.1.0 and syncs high-level Direct/user/media/story behavior plus Reel Facebook destination helpers through instagrapi 2.8.19. Realtime helpers can receive Direct message sync payloads, publish lightweight Direct actions over MQTT, and subscribe to FBNS push notifications.

from aiograpi import Client

cl = Client()
await cl.login(USERNAME, PASSWORD)


def handle_message(payload):
    print(payload)


cl.realtime_on("message", handle_message)
rt = await cl.realtime_connect()
await rt.direct_subscribe()

await rt.direct_send_text(thread_id, "Hello from MQTT")

while True:
    await cl.realtime_read_once()

See the Realtime MQTT guide for Direct sync, MQTT Direct actions, and FBNS push examples.

Basic Usage

from aiograpi import Client

cl = Client()
await cl.login(ACCOUNT_USERNAME, ACCOUNT_PASSWORD)

user_id = await cl.user_id_from_username("example")
medias = await cl.user_medias(user_id, 20)

The full example

from aiograpi import Client
from aiograpi.types import StoryMention, StoryMedia, StoryLink, StoryHashtag

cl = Client()
await cl.login(USERNAME, PASSWORD, verification_code="<2FA CODE HERE>")

media_pk = await cl.media_pk_from_url('https://www.instagram.com/p/CGgDsi7JQdS/')
media_path = await cl.video_download(media_pk)
example = await cl.user_info_by_username('example')
hashtag = await cl.hashtag_info('dhbastards')

await cl.video_upload_to_story(
    media_path,
    "Credits @example",
    mentions=[StoryMention(user=example, x=0.49892962, y=0.703125, width=0.8333333333333334, height=0.125)],
    links=[StoryLink(webUri='https://github.com/subzeroid/aiograpi')],
    hashtags=[StoryHashtag(hashtag=hashtag, x=0.23, y=0.32, width=0.5, height=0.22)],
    medias=[StoryMedia(media_pk=media_pk, x=0.5, y=0.5, width=0.6, height=0.8)]
)

Requests

  • Public or Graphql (anonymous request via web api) methods have a suffix _gql
  • Private (authorized request via mobile api) 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):

async def media_info(media_pk):
    try:
        return await 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 await self.media_info_v1(media_pk)

Detailed Documentation

To learn more about the various ways aiograpi can be used, read the Usage Guide page.