aiograpi Examples

These scripts are small runnable starting points for common aiograpi tasks. They keep credentials out of source code and use environment variables so they can be copied into applications without hard-coded secrets.

Setup

Install the package and export credentials:

python -m pip install -U aiograpi

export IG_USERNAME="your_username"
export IG_PASSWORD="your_password"
export IG_SESSION_FILE="./ig_settings.json"

Optional settings:

export IG_PROXY="http://user:pass@host:port"
export IG_PUBLIC_TRANSPORT="curl"
export IG_PUBLIC_TRANSPORT_IMPERSONATE="chrome136"

IG_SESSION_FILE is reused between runs. Keep that file private; it contains session data.

Scripts

Script	Purpose
_common.py	Shared async login, proxy, session, and environment helpers used by the examples.
public_lookup.py	Public profile lookup with optional public_transport="curl".
download_user_media.py	Login, list recent media for a username, and download photos/videos/albums.
upload_media.py	Upload a feed photo, feed video, Reel, or Trial Reel.
upload_story.py	Upload a photo or video story, optionally with a link sticker.
direct_message.py	Send a Direct text message to user IDs or thread IDs.
realtime_direct.py	Receive Direct message sync payloads over Realtime MQTT.

Public lookup

python examples/public_lookup.py instagram
IG_PUBLIC_TRANSPORT=curl python examples/public_lookup.py instagram

Download media

python examples/download_user_media.py instagram --amount 5 --folder ./downloads

Upload media

python examples/upload_media.py photo ./photo.jpg --caption "Hello from aiograpi"
python examples/upload_media.py video ./video.mp4 --thumbnail ./thumb.jpg --caption "Feed video"
python examples/upload_media.py reel ./reel.mp4 --thumbnail ./thumb.jpg --caption "Reel"
python examples/upload_media.py trial-reel ./reel.mp4 --thumbnail ./thumb.jpg --caption "Trial Reel"

For Android/Pydroid environments, pass --thumbnail for videos and Reels or configure executable ffmpeg.

Upload story

python examples/upload_story.py photo ./story.jpg --caption "Story"
python examples/upload_story.py video ./story.mp4 --thumbnail ./thumb.jpg --link https://github.com/subzeroid/aiograpi

Story assets should usually be 9:16, for example 720x1280.

Direct message

python examples/direct_message.py --user-ids 123456789 --text "Hello"
python examples/direct_message.py --thread-ids 340282366841710301949128122292511813703 --text "Hello thread"

Use exactly one target type: --user-ids or --thread-ids.

Realtime Direct MQTT

python examples/realtime_direct.py --limit 1
IG_REALTIME_DIRECT_LIMIT=0 python examples/realtime_direct.py

The script logs in, subscribes to Direct message sync over Realtime MQTT, and prints received payloads as JSON.