aiograpi

https://github.com/subzeroid/aiograpi
Admin
aiograpi is an asynchronous Instagram Private API wrapper for Python that enables accessing public...
Tokens:357,717
Snippets:2,215
Trust Score:8.7
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Set up local environment with uv

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/development-guide.md

Alternative setup using uv to create a virtual environment and install the project with test extras.

```bash
uv venv
source .venv/bin/activate
uv pip install -e ".[test]"
pre-commit install
```

--------------------------------

### Run example scripts

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/examples.md

Shows how to run the common example scripts. The public_lookup.py example can optionally use IG_PUBLIC_TRANSPORT=curl. Video uploads in Android environments should pass --thumbnail or install optional video dependencies (MoviePy 2.2.1 and ffmpeg).

```bash
python examples/public_lookup.py instagram
IG_PUBLIC_TRANSPORT=curl python examples/public_lookup.py instagram
python examples/download_user_media.py instagram --amount 5 --folder ./downloads
python examples/upload_media.py reel ./reel.mp4 --thumbnail ./thumb.jpg --caption "Reel"
python examples/upload_story.py photo ./story.jpg --caption "Story"
python examples/direct_message.py --user-ids 123456789 --text "Hello"
python examples/realtime_direct.py --limit 1
```

--------------------------------

### Set up development environment with uv

Source: https://github.com/subzeroid/aiograpi/blob/main/CONTRIBUTING.md

Alternative setup using uv, keeping pyproject.toml as the source of truth. Creates a virtual environment, activates it, syncs dependencies with test extras, and installs pre-commit hooks.

```bash
uv venv
source .venv/bin/activate
uv sync --extra test
pre-commit install
```

--------------------------------

### Set up local environment with venv and install test extras

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/development-guide.md

Creates a virtual environment, activates it, upgrades pip, installs the project with test extras, and installs pre-commit hooks.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"
pre-commit install
```

--------------------------------

### Download album by media PK with aiograpi

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Demonstrates downloading an album by media PK. The output shows a list of PosixPaths for the album's media files. This example follows the same login and client setup as the previous video download example.

```python
>>> await cl.media_pk_from_url("http://www.instagram.com/p/BjNLpA1AhXM/")
1787135824035452364

>>> await cl.album_download(1787135824035452364)
[PosixPath('/app/example_1787135361353462176.mp4'),
 PosixPath('/app/example_1787135762219834098.mp4'),
 PosixPath('/app/example_1787133803186894424.jpg')]
```

--------------------------------

### Explore page usage example

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/explore.md

Example usage of the explore page helpers. It logs in, gets the explore page, gets media info for a media URL, and reports the media. The output of explore_page_media_info is shown as {...} and report_explore_media returns True.

```python
>>> from aiograpi import Client
>>> cl = Client()
>>> await cl.login(USERNAME, PASSWORD)

>>> page = await cl.explore_page()

>>> media_pk = await cl.media_pk_from_url(
...     "https://www.instagram.com/p/ByU3LAslgWY/"
... )
>>> await cl.explore_page_media_info(media_pk)
{...}

>>> await cl.report_explore_media(media_pk)
True
```

--------------------------------

### Account management example with aiograpi Client

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/account.md

Interactive Python session showing account management methods: account_info(), account_edit(), account_change_picture(), account_convert_to_creator(), send_password_reset(), send_confirm_email(), confirm_email(), send_confirm_phone_number(), and confirm_phone_number(). The example includes sample outputs, such as a dict with account details and status responses. Note that send_password_reset() only starts the recovery flow; it does not set a new password.

```python
>>> from aiograpi import Client
>>> cl = Client()
>>> await cl.login(USERNAME, PASSWORD)
>>> (await cl.account_info()).dict()
{'pk': 1903424587,
 'username': 'example',
 'full_name': 'Example Example',
 'is_private': False,
 'profile_pic_url': HttpUrl('https://instagram.frix7-1.fna.fbcdn.net/v/t51.2885-19/s150x150/200092102_504535360754500_904902738723095864_n.jpg?tp=1&_nc_ht=instagram.frix7-1.fna.fbcdn.net&_nc_ohc=T2ZT6yA6XzoAX9MvAQA&edm=AJlpnE4BAAAA&ccb=7-4&oh=3865b51bb33b365c9de8bcf9775e519c&oe=60E982F2&_nc_sid=312772'),
 'is_verified': False,
 'biography': 'Engineer: Python, JavaScript, Erlang, Go, Swift\n@dhbastards \n@bestskatetrick \n@asphalt_kings_lb \n@best_drift_daily \n@wrclive \n@surferyone \n@bmxtravel',
 'external_url': 'https://example.org/',
 'is_business': False,
 'birthday': '1984-01-01',
 'phone_number': '+79991234567',
 'gender': 1,
 'email': '...@gmail.com'}

>>> await cl.account_edit(external_url='https://github.com/subzeroid/aiograpi')
Account(pk=1903424587, username='example', ..., external_url='https://github.com/subzeroid/aiograpi')

>>> media_pk = await cl.media_pk_from_url('https://www.instagram.com/p/BWnh360Fitr/')
1560364774164147051

>>> profile_pic_path = await cl.photo_download(media_pk, folder='/tmp')
PosixPath('/tmp/example_1560364774164147051.jpg')

>>> await cl.account_change_picture(profile_pic_path)
UserShort(pk=1903424587, username='example', ...)

>>> await cl.account_convert_to_creator(category_id="2347428775505624")
Account(pk=1903424587, username='example', ..., account_type=3)

>>> await cl.send_password_reset("example")
{'status': 'ok'}

>>> await cl.send_confirm_email("addr@example.com")
{
    'is_email_legit': False,
    'title': 'Email Already in Use',
    'body': 'The email address you entered is already used on your account. Enter a different one to update your contact info.',
    'error_type': 'email_unchanged',
    'status': 'ok'
}

>>> await cl.confirm_email("addr@example.com", "123456")
{'status': 'ok'}

>>> await cl.send_confirm_phone_number("+5599999999")
{
    'action': 'sms_sent',
    'phone_verification_settings': {'max_sms_count': 2,
    'resend_sms_delay_sec': 60,
    'robocall_count_down_time_sec': 30,
    'robocall_after_max_sms': True},
    'status': 'ok'
}

>>> await cl.confirm_phone_number("+5599999999", "123456", has_sms_consent=True)
{'status': 'ok'}

```

--------------------------------

### Story download and archive example

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/story.md

Demonstrates downloading a story from a URL, retrieving story info, downloading media by URL, and fetching archived stories. The example shows the expected output paths for downloaded files.

```python
>>> await cl.story_download(await cl.story_pk_from_url('https://www.instagram.com/stories/example/2581281926631793076/'))
PosixPath('/app/189361307_229642088942817_9180243596650100310_n.mp4')

>>> s = await cl.story_info(2581281926631793076)

>>> await cl.story_download_by_url(s.video_url)  # url to mp4 file
PosixPath('/app/189361307_229642088942817_9180243596650100310_n.mp4')

>>> await cl.story_download_by_url(s.thumbnail_url)  # URL to jpg file
PosixPath('/app/191260083_2908005872746895_8988438451809588865_n.jpg')

>>> days = await cl.archive_story_days(amount=5)
>>> stories = await cl.archive_stories(amount=10)
```

--------------------------------

### Location search, complete, build, and info example

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/location.md

Demonstrates the main location workflow: search by coordinates, complete blank fields, build serialized JSON, and fetch location info. The example uses the aiograpi Client and shows the output of each method call.

```python
>>> from aiograpi import Client

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

>>> location = (await cl.location_search(59.96, 30.29))[0]
>>> location.dict()
{'pk': None,
 'name': 'Russia, Saint-Petersburg',
 'address': 'Russia, Saint-Petersburg',
 'lng': 30.30605,
 'lat': 59.93318,
 'external_id': 107617247320879,
 'external_id_source': 'facebook_places'}

>>> location = await cl.location_complete(location)
>>> location.dict()
{'pk': 107617247320879,
 'name': 'Russia, Saint-Petersburg',
 'address': 'Russia, Saint-Petersburg',
 'lng': 30.30605,
 'lat': 59.93318,
 'external_id': 107617247320879,
 'external_id_source': 'facebook_places'}

>>> await cl.location_build(location)
'{"name":"Russia, Saint-Petersburg","address":"Russia, Saint-Petersburg","lat":59.93318,"lng":30.30605,"external_source":"facebook_places","facebook_places_id":107617247320879}'

>>> location = await cl.location_info(107617247320879)
>>> location.dict()
{'pk': 107617247320879,
 'name': 'Russia, Saint-Petersburg',
 'address': '',
 'lng': 30.30605,
 'lat': 59.93318,
 'external_id': None,
 'external_id_source': None}
```

--------------------------------

### Install aiograpi and set credentials

Source: https://github.com/subzeroid/aiograpi/blob/main/examples/README.md

Install the aiograpi package and set required environment variables for credentials and session file. The session file is reused between runs and must be kept private.

```bash
python -m pip install -U aiograpi

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

--------------------------------

### Manage Notification Settings Example

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/notification.md

Example usage of notification helpers: enable comments notifications for followers only, turn off likes notifications, and mute all notifications for one hour. Requires an authenticated client.

```python
from aiograpi import Client

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

await cl.notification_comments("following_only")
await cl.notification_settings("likes", "off")
await cl.notification_mute_all("1_hour")
```

--------------------------------

### TOTP setup and code generation with aiograpi

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/totp.md

Walks through TOTP setup: generate a seed, generate a code, enable 2FA (which returns backup keys), and disable 2FA. The output shown is from an interactive Python session. Note that the backup keys are returned only at enable time and may not be retrievable later.

```python
>>> from aiograpi import Client
>>> cl = Client()
>>> await cl.login(USERNAME, PASSWORD)

>>> seed = await cl.totp_generate_seed()
"67EIYPWCIJDTTVX632NEODKEU2PY5BIW"

>>> code = cl.totp_generate_code(seed)
"123456"

>>> await cl.totp_enable(code)
["1234 5678", "1234 5678", "1234 5678", "1234 5678", "1234 5678"]

>>> await cl.totp_disable()
True
```

--------------------------------

### Full example: upload video to story with mentions, links, hashtags, and media

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/index.md

Full example: logs in with optional 2FA code, downloads a video, and uploads it to a story with mentions, links, hashtags, and media attachments. Requires the aiograpi types StoryMention, StoryMedia, StoryLink, and StoryHashtag.

```python
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)]
)
```

--------------------------------

### Minimal clip upload example

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/pydroid.md

Minimal clip upload example for Pydroid. If thumbnail is omitted, a working ffmpeg executable is required for automatic thumbnail generation.

```python
from pathlib import Path

from aiograpi import Client

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

media = await cl.clip_upload(
    Path("reel.mp4"),
    "Uploaded from Pydroid",
    thumbnail=Path("reel-thumb.jpg"),
)
print(media.pk)
```

--------------------------------

### Install aiograpi with pip

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/login-migration.md

Install the package normally. curl_cffi is a required dependency.

```bash
pip install aiograpi
```

--------------------------------

### bloks_two_step_verification_entrypoint()

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/totp.md

Low-level helper to start the two-step verification flow.

```APIDOC
## bloks_two_step_verification_entrypoint()

### Description
Low-level helper to start the two-step verification flow.

### Method
bloks_two_step_verification_entrypoint

### Parameters
- **context** (string) - Required - The two-step verification context from Instagram's login challenge response.

### Request Example
```python
await cl.bloks_two_step_verification_entrypoint(context)
```
```

--------------------------------

### Install aiograpi with pip

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/getting-started.md

Install the aiograpi package using pip. Requires Python 3.10 or higher.

```bash
python -m pip install aiograpi
```

--------------------------------

### Install pre-commit globally with pipx

Source: https://github.com/subzeroid/aiograpi/blob/main/CONTRIBUTING.md

Globally installs pre-commit via pipx. Do not use pipx to install aiograpi itself, as it is a library package, not a command-line application.

```bash
pipx install pre-commit
```

--------------------------------

### Example: Using insights methods

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/insight.md

Shows how to use insights_media_feed_all, insights_account, and insights_media after logging in. Requires an authenticated business/professional account; personal accounts may raise UserError.

```python
from aiograpi import Client

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

await cl.insights_media_feed_all("VIDEO", "ONE_WEEK", "LIKE_COUNT", 42)
await cl.insights_account()

media_pk = await cl.media_pk_from_url('https://www.instagram.com/p/CP5h-I1FuPr/')
await cl.insights_media(media_pk)
```

--------------------------------

### clip_info_for_creation

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Gets Reel creation preflight configuration for the current user.

```APIDOC
## clip_info_for_creation()

### Description
Gets Reel creation preflight configuration for the current user.

### Method
SDK method call

### Parameters
None

### Response
Returns a `Dict` containing the Reel creation preflight configuration.
```

--------------------------------

### Install aiograpi on Termux

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/termux.md

Updates Termux packages, installs Python and Pillow, and installs aiograpi from the Termux User Repository PyPI index. The extra index provides Android wheels for native packages like pydantic-core.

```bash
pkg update
pkg install python python-pillow
python -m pip install -U pip setuptools wheel
python -m pip install --extra-index-url https://termux-user-repository.github.io/pypi/ aiograpi
```

--------------------------------

### Hello world: login and fetch user info

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/getting-started.md

Basic async example that logs in and fetches user info and recent media. Replace YOUR_USERNAME and YOUR_PASSWORD with real credentials. Requires an Instagram account; fresh or unverified accounts may be flagged.

```python
import asyncio
from aiograpi import Client

async def main():
    client = Client()
    await client.login("YOUR_USERNAME", "YOUR_PASSWORD")
    user = await client.user_info_by_username("instagram")
    print(user.full_name, user.follower_count)
    medias = await client.user_medias(user.pk, amount=3)
    for m in medias:
        print(m.code, m.caption_text[:60])

asyncio.run(main())
```

--------------------------------

### Realtime MQTT and Direct example

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/index.md

Sets up a realtime MQTT connection to receive Direct message sync payloads, subscribe to Direct, and send a text message over MQTT. Requires aiograpi 1.3.0 or later and a logged-in client.

```python
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()
```

--------------------------------

### Install aiograpi[curl] extra

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/public-transport.md

Installs the optional curl transport for public web endpoints sensitive to browser TLS fingerprints. Requires curl-adapter>=1.2.3 for compatibility with urllib3 2.8; upgrade older adapters with pip install --upgrade "curl-adapter>=1.2.3".

```bash
pip install "aiograpi[curl]"
```

--------------------------------

### Create a music note using the music browser

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/notes.md

Example of creating a music note by first retrieving the music browser response, selecting a track, and then calling create_music_note with the track, text, audience, and alacorn_session_id.

```python
browser = await cl.notes_music_browser()
track = browser["items"][0]["track"]
note = await cl.create_music_note(
    track,
    text="Now playing",
    audience=NoteAudience.CLOSE_FRIENDS,
    alacorn_session_id=browser["alacorn_session_id"],
)
```

--------------------------------

### media_pk_from_code(code: str)

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Get media PK from a shortcode.

```APIDOC
## media_pk_from_code(code: str)

### Description
Get media PK from a shortcode.

### Method
GET

### Endpoint
media/{code}/pk_from_code/

### Parameters
#### Path Parameters
- **code** (str) - Required - The shortcode of the media.

### Response
#### Success Response (200)
- **media_pk** (int) - The media PK.

#### Response Example
{
  "media_pk": 2278584739065882267
}
```

--------------------------------

### media_pk_from_url(url: str)

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Get media PK from a URL.

```APIDOC
## media_pk_from_url(url: str)

### Description
Get media PK from a URL.

### Method
GET

### Endpoint
media/{url}/pk_from_url/

### Parameters
#### Path Parameters
- **url** (str) - Required - The URL of the media.

### Response
#### Success Response (200)
- **media_pk** (int) - The media PK.

#### Response Example
{
  "media_pk": 1787135824035452364
}
```

--------------------------------

### Pass settings dictionary to Client

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/interactions.md

Shows the settings dictionary format accepted by the Client constructor and how to pass it. The example uses an older app profile without a Bloks hash; before a fresh CAA login, follow the older-profile migration steps.

```python
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 your 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)",
   "public_transport": "requests",
   "private_transport": "curl",
   "public_transport_impersonate": "chrome136",
   "tls_verify": True
}

cl = Client(settings)
```

--------------------------------

### Get fundraiser info with standalone_fundraiser_info_v1

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/fundraiser.md

Shows how to log in and retrieve fundraiser information for a user using the standalone_fundraiser_info_v1 method. The output is a dictionary, represented here as {...}.

```python
>>> from aiograpi import Client
>>> cl = Client()
>>> await cl.login(USERNAME, PASSWORD)

>>> user_id = await cl.user_id_from_username("instagram")
>>> await cl.standalone_fundraiser_info_v1(user_id)
{...}
```

--------------------------------

### Upload story (photo or video)

Source: https://github.com/subzeroid/aiograpi/blob/main/examples/README.md

Upload a photo or video story, optionally with a link sticker. Story assets should usually be 9:16, for example 720x1280.

```bash
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
```

--------------------------------

### Get highlight info and user highlights

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/highlight.md

Shows how to fetch a single highlight by its PK and list a user's highlights. The first call returns a Highlight object converted to a dict with fields like pk, cover_media, user, title, and media_ids; the second returns a list of Highlight objects.

```python
>>> (await cl.highlight_info(17895485201104054)).dict()
{
    'pk': 17895485201104054,
    'id': 'highlight:17895485201104054',
    'latest_reel_media': 1622366765,
    'cover_media': {
        'cropped_image_version': {'width': 150, 'height': 150, 'url': 'https://instagram.frix7-1.fna.fbcdn.net/v/t51.2885-...'},
        'crop_rect': [0, 0.21855760773966576, 1, 0.7814423922603342],
        'media_id': '2584323966581791455_8641392340'
    },
    'user': {
        'pk': 8641392340,
        'username': 'bestskatetrick',
        'full_name': 'The Best Skate Tricks',
        'profile_pic_url': HttpUrl('https://instagram.frix7-1.fna.fbcdn.net/v/t51.2885-19/s150x150/6526...'),
        'profile_pic_url_hd': None,
        'is_private': False,
        'stories': []
    },
    'title': 'Picnic 2021',
    'created_at': datetime.datetime(2021, 5, 29, 19, 39, 15, tzinfo=datetime.timezone.utc),
    'is_pinned_highlight': False,
    'media_count': 19,
    'media_ids': [2584323966581791455, 2584328925731679183, 2584328595757338887, ...],  # story ids
    'items': [Story, Story, Story, ...]
}

>>> await cl.user_highlights(29817608135)
[Highlight(pk='17907771728171896', id='highlight:17907771728171896', latest_reel_media=1638039687, ...), ...]
```

--------------------------------

### media_info_gql(media_pk: int)

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Get Media from PK by Public Graphql API.

```APIDOC
## media_info_gql(media_pk: int)

### Description
Get Media from PK by Public Graphql API.

### Method
GET

### Endpoint
media/{media_pk}/info_gql/

### Parameters
#### Path Parameters
- **media_pk** (int) - Required - The media PK.

### Response
#### Success Response (200)
- **Media** (object) - The media object.

#### Response Example
{
  "media": {}
}
```

--------------------------------

### media_info_v1(media_pk: int)

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Get Media from PK by Private Mobile API.

```APIDOC
## media_info_v1(media_pk: int)

### Description
Get Media from PK by Private Mobile API.

### Method
GET

### Endpoint
media/{media_pk}/info_v1/

### Parameters
#### Path Parameters
- **media_pk** (int) - Required - The media PK.

### Response
#### Success Response (200)
- **Media** (object) - The media object.

#### Response Example
{
  "media": {}
}
```

--------------------------------

### clip_share_to_fb_config

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Get Reel Facebook sharing configuration for the current user.

```APIDOC
## clip_share_to_fb_config() -> Dict

### Description
Get Reel Facebook sharing configuration for the current user.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
None

### Returns
- **Dict** - Reel Facebook sharing configuration.
```

--------------------------------

### clip_share_to_fb_unified_config

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Get the Android cross-posting unified config used by the Reel composer.

```APIDOC
## clip_share_to_fb_unified_config() -> Dict

### Description
Get the Android cross-posting unified config used by the Reel composer.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
None

### Returns
- **Dict** - Unified cross-posting config.
```

--------------------------------

### media_share_to_fb_unified_config

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Gets Android's unified cross-posting configuration for Facebook destinations.

```APIDOC
## media_share_to_fb_unified_config()

### Description
Gets Android's unified cross-posting configuration for Facebook destinations.

### Method
SDK method call

### Parameters
None

### Response
Returns a `dict` containing the unified cross-posting configuration.
```

--------------------------------

### Paginate hashtag medias with cursor

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Example from the linked issue for loading new posts from a hashtag. Shows paginated retrieval with hashtag_medias_paginated() and low-level chunk retrieval with hashtag_medias_v1_chunk(), including the returned cursor values.

```python
>>> medias, cursor = await cl.hashtag_medias_paginated('test', amount=32, tab_key='recent')
>>> next_medias, cursor = await cl.hashtag_medias_paginated('test', amount=32, tab_key='recent', end_cursor=cursor)

>>> medias, cursor = await cl.hashtag_medias_v1_chunk('test', max_amount=32, tab_key='recent')
>>> len(medias)
32
>>> cursor
QVFDR0dzT3FJT0V4amFjMaQ3czlGVzRKV3FNWDJqaE1mWmltWU5VWGYtbnV6RVpoOUlsR3dCN05RRmpLc2R5SVlCQTNaekV5bUVOV0F4Vno1MDkxN1Nndg==

# NEXT cursor:

>>> medias, cursor = await cl.hashtag_medias_v1_chunk('test', max_amount=32, tab_key='recent', max_id=cursor)
>>> len(medias)
32
>>> cursor
QVFEUXpfM0RtaDdmMExPQ0k0UWRlaHFJa2RVdVlaX01LTzhkNF9Dd1N2UlhtVy1vSTZvMERfYW5XN205OTBRNFBCSVJ2ZTVfTG5ZMXVmY0VJbUM5TU9URQ==
```

--------------------------------

### Search music and get first result

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/track.md

Searches for music with the query "love" and prints the dictionary of the first result. The output includes track metadata and cover artwork URI.

```python
>>> (await cl.search_music("love"))[0].dict()
{
'id': '354372829354341',
'title': 'Love Your Voice',
'subtitle': '',
'display_artist': 'JONY',
'audio_cluster_id': 410742646320351,
'artist_id': None,
'cover_artwork_uri': HttpUrl('https://cdn.fbsbx.com/v/t65.14500-21/191897578_1074647849725858_3973554110966662866_n.jpg?stp=cp0_dst-jpg_e15_p526x296_q65&_nc_cat=1&ccb=1-7&_nc_sid=cbead8&_nc_ohc=ugygksMclf4AX_u7L7g&_nc_ht=cdn.fbsbx.com&oh=00_AT89FBXl6h7Q6zytlI5cA4UIG_zQkK_DsOqyUqyXk1zyIg&oe=62DAEA82', scheme='https', host='cdn.fbsbx.com', tld='com', host_type='domain', port='443', path='/v/t65.14500-21/191897578_1074647849725858_3973554110966662866_n.jpg', query='stp=cp0_dst-jpg_e15_p526x296_q65&_nc_cat=1&ccb=1-7&_nc_sid=cbead8&_nc_ohc=ugygksMclf4AX_u7L7g&_nc_ht=cdn.fbsbx.com&oh=00_AT89FBXl6h7Q6zytlI5cA4UIG_zQkK_DsOqyUqyXk1zyIg&oe=62DAEA82')
```

--------------------------------

### Get music canonical IDs from reels

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/track.md

Logs in and retrieves the music canonical IDs from the first 10 reels. The output is a list of string IDs.

```python
>>> from aiograpi import Client
>>> cl = Client()
>>> await cl.login(USERNAME, PASSWORD)

>>> [media.clips_metadata['music_canonical_id'] for media in (await cl.reels(amount=10))]

['18159860503036324',
 '18245182426110798',
 '18156435169051995',
 '18274086877034385',
 '18243482860109137',
 '18244791958105000',
 '18310451203035205',
 '18293984647065921',
 '18154598032011335',
 '18301950994013617']
```

--------------------------------

### Get oEmbed data with cl.media_oembed()

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Fetches oEmbed data for a public Instagram post URL and prints it as a dictionary. The response includes author, provider, thumbnail, and embed HTML information.

```python
>>> (await cl.media_oembed("https://www.instagram.com/p/B3mr1-OlWMG/")).dict()
{'version': '1.0',
 'title': 'В гостях у ДК @delai_krasivo_kaifui',
 'author_name': 'example',
 'author_url': 'https://www.instagram.com/example',
 '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...0655800983_n.jpg',
 'thumbnail_width': 640,
 'thumbnail_height': 480,
 'can_view': True}
```

--------------------------------

### Get or create a direct thread by participants

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/direct.md

Retrieves or creates a direct thread with the specified participants. The example uses the current user's ID and returns a DirectThread object.

```python
>>> await cl.direct_thread_by_participants([cl.user_id])
DirectThread(pk=178612312342, id=340282366812312312312341298762, messages=[DirectMessage(id=30076214123123123123123864, user_id=1903424587, thread_id=None, timestamp=datetime.datetime(2021, 8, 31, 18, 33, 49, 107154, ...)
```

--------------------------------

### Set IG credentials environment variables

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/examples.md

Sets the environment variables required by the example scripts to read credentials and runtime options instead of hard-coding secrets.

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

--------------------------------

### Search for a place with coordinates and get location info

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/location.md

Searches for a place by name and coordinates using fbsearch_places, takes the first result, and then retrieves detailed location info with location_info. The example shows how coordinates can be passed and the resulting location details.

```python
>>> place = (await cl.fbsearch_places("Villa Sirot", 46.7032028502, 4.3093986902))[0]
>>> place.dict()
{'pk': 1001956449,
 'name': 'Villa Sirot',
 'phone': '',
 'website': '',
 'category': '',
 'hours': {},
 'address': None,
 'city': None,
 'zip': None,
 'lng': 4.3093986902426,
 'lat': 46.703202850229,
 'external_id': 165573396905197,
 'external_id_source': 'facebook_places'}

>>> (await cl.location_info(place.pk)).dict()
{'pk': 1001956449,
 'name': 'Villa Sirot',
 'phone': '',
 'website': None,
 'category': 'Local Business',
 'hours': {'status': '',
  'current_status': '',
  'hours_today': '',
  'schedule': []},
 'address': None,
 'city': None,
 'zip': None,
 'lng': None,
 'lat': None,
 'external_id': 165573396905197,
 'external_id_source': None}
```

--------------------------------

### Search for a place and get location info with fbsearch_places and location_info

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/location.md

Searches for a place by name using fbsearch_places, picks the third result, and then retrieves detailed location info with location_info. The example shows the difference between the search result and the full location details.

```python
>>> place = (await cl.fbsearch_places('Perch'))[2]
>>> place.dict()
{
 'pk': 3824034,
 'name': 'Perch',
 'phone': '',
 'website': '',
 'category': '',
 'hours': {},
 'address': None,
 'city': None,
 'zip': None,
 'lng': -118.25135,
 'lat': 34.04882,
 'external_id': 207298912632228,
 'external_id_source': 'facebook_places'
}

>>> (await cl.location_info(place.pk)).dict()
{
 'pk': 3824034,
 'name': 'Perch',
 'phone': '(213) 802-1770',
 'website': 'http://www.perchla.com',
 'category': '',
 'hours': {},
 'address': '448 S Hill St',
 'city': 'Los Angeles, California',
 'zip': '90013',
 'lng': -118.25135,
 'lat': 34.04882,
 'external_id': None,
 'external_id_source': None
}
```

--------------------------------

### user_videos_v1(user_id: str, amount: int = 50)

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Get a user's video by Private Mobile API.

```APIDOC
## user_videos_v1(user_id: str, amount: int = 50)

### Description
Get a user's video by Private Mobile API.

### Method
GET

### Endpoint
user/{user_id}/videos_v1/

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The user ID.

#### Query Parameters
- **amount** (int) - Optional - Number of videos to retrieve. Default is 50.

### Response
#### Success Response (200)
- **List[Media]** (array) - List of media objects.

#### Response Example
{
  "medias": []
}
```

--------------------------------

### Basic Direct actions with Client

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/direct.md

Shows basic Direct actions: logging in, fetching the first thread, and inspecting its pk and users. The output demonstrates the structure of a UserShort object.

```python
>>> from aiograpi import Client
>>> cl = Client()
>>> await cl.login(USERNAME, PASSWORD)

>>> thread = (await cl.direct_threads(1))[0]
>>> thread.pk
18123276039123479

>>> thread.users
[UserShort(pk=123123123, username='something', full_name='Dima Something', profile_pic_url=HttpUrl('https://instagram.frix7-1.fna.fbcdn.net/v/t51.2885-19/s150x150/11374323_1630877790512376_1081658215_a.jpg?_nc_ht=instagram.frix7-1.fna.fbcdn.net&_nc_ohc=k22oMvVv8xEAX-UEVRB&edm=AI8ESKwBAAAA&ccb=7-4&oh=be799948b28f19d85158153d886d16d3&oe=6135D80F&_nc_sid=195af5', scheme='https', host='instagram.frix7-1.fna.fbcdn.net', tld='net', host_type='domain', path='/v/t51.2885-19/s150x150/11374323_1630877790512376_1081658215_a.jpg', query='_nc_ht=instagram.frix7-1.fna.fbcdn.net&_nc_ohc=k22oMvVv8xEAX-UEVRB&edm=AI8ESKwBAAAA&ccb=7-4&oh=be799948b28f19d85158153d886d16d3&oe=6135D80F&_nc_sid=195af5'), profile_pic_url_hd=None, is_private=False, stories=[])]
```

--------------------------------

### Get email code via Gmail IMAP

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/challenge_resolver.md

Example of retrieving the challenge code from a Gmail inbox using IMAP. It searches for unseen emails, extracts the code using regex, and marks emails as read. Returns False if no code is found.

```python
async def get_code_from_email(username):
    mail = imaplib.IMAP4_SSL("imap.gmail.com")
    mail.login(CHALLENGE_EMAIL, CHALLENGE_PASSWORD)
    mail.select("inbox")
    result, data = mail.search(None, "(UNSEEN)")
    assert result == "OK", "Error1 during get_code_from_email: %s" % result
    ids = data.pop().split()
    for num in reversed(ids):
        mail.store(num, "+FLAGS", "\\Seen")  # mark as read
        result, data = mail.fetch(num, "(RFC822)")
        assert result == "OK", "Error2 during get_code_from_email: %s" % result
        msg = email.message_from_string(data[0][1].decode())
        payloads = msg.get_payload()
        if not isinstance(payloads, list):
            payloads = [msg]
        code = None
        for payload in payloads:
            body = payload.get_payload(decode=True).decode()
            if "<div" not in body:
                continue
            match = re.search(">([^>]*?({u})[^<]*?)<".format(u=username), body)
            if not match:
                continue
            print("Match from email:", match.group(1))
            match = re.search(r">(\d{6})<", body)
            if not match:
                print('Skip this email, "code" not found')
                continue
            code = match.group(1)
            if code:
                return code
    return False
```

--------------------------------

### user_medias_v1(user_id: str, amount: int = 18)

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Get a user's media by Private Mobile API.

```APIDOC
## user_medias_v1(user_id: str, amount: int = 18)

### Description
Get a user's media by Private Mobile API.

### Method
GET

### Endpoint
user/{user_id}/medias_v1/

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The user ID.

#### Query Parameters
- **amount** (int) - Optional - Number of media to retrieve. Default is 18.

### Response
#### Success Response (200)
- **List[Media]** (array) - List of media objects.

#### Response Example
{
  "medias": []
}
```

--------------------------------

### usertag_medias_paginated(user_id: str, amount: int = 20, end_cursor: str = "")

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Get tagged medias with pagination cursor.

```APIDOC
## usertag_medias_paginated(user_id: str, amount: int = 20, end_cursor: str = "")

### Description
Get tagged medias with pagination cursor.

### Method
GET

### Endpoint
user/{user_id}/usertag_medias_paginated/

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The user ID.

#### Query Parameters
- **amount** (int) - Optional - Number of medias to retrieve. Default is 20.
- **end_cursor** (str) - Optional - Cursor for pagination. Default is empty string.

### Response
#### Success Response (200)
- **Tuple[List[Media], str]** (array) - List of media objects and next cursor.

#### Response Example
{
  "medias": [],
  "next_cursor": "string"
}
```

--------------------------------

### Sync media-pk helpers before and after

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/migration.md

Before and after code for three pure media-pk helpers that became synchronous in version 0.2.0.

```python
# Before
pk    = await client.media_pk_from_code(code)
code  = await client.media_code_from_pk(pk)
short = await client.media_pk(media_id)

# After
pk    = client.media_pk_from_code(code)
code  = client.media_code_from_pk(pk)
short = client.media_pk(media_id)  # staticmethod
```

--------------------------------

### Client settings constructor before and after

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/migration.md

Before and after code showing that settings dict is now deep-copied.

```python
# Before
Client(settings={"some": "dict"})  # caller-supplied dict was held by reference

# After
Client(settings={"some": "dict"})  # deepcopy'd, mutating it later won't leak in
```

--------------------------------

### user_videos_chunk_v1(user_id: int, end_cursor: str = "")

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Get a page of user's video by Private Mobile API.

```APIDOC
## user_videos_chunk_v1(user_id: int, end_cursor: str = "")

### Description
Get a page of user's video by Private Mobile API.

### Method
GET

### Endpoint
user/{user_id}/videos_chunk_v1/

### Parameters
#### Path Parameters
- **user_id** (int) - Required - The user ID.

#### Query Parameters
- **end_cursor** (str) - Optional - Cursor for pagination. Default is empty string.

### Response
#### Success Response (200)
- **Tuple[List[Media], str]** (array) - List of media objects and next cursor.

#### Response Example
{
  "medias": [],
  "next_cursor": "string"
}
```

--------------------------------

### Install aiograpi video dependencies

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/index.md

Install the optional video dependencies for aiograpi. The second command installs MoviePy 2.2.1 without dependencies to avoid downgrading Pillow below 12.3.0, which is kept for security fixes.

```bash
pip install "aiograpi[video]"
```

```bash
pip install --no-deps "moviepy==2.2.1"
```

--------------------------------

### Upload a trial Reel with clip_upload

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Uploads a trial Reel using the same clip_upload method as regular Reels. Pass thumbnail=... to avoid automatic thumbnail generation in Android environments, or install optional video dependencies (MoviePy 2.2.1 and executable ffmpeg).

```python
media = await cl.clip_upload(
    Path("reel.mp4"),
    "Trying a new format",
    thumbnail=Path("reel-thumb.jpg"),
    trial=True,
)
```

--------------------------------

### Basic async login and media fetch

Source: https://github.com/subzeroid/aiograpi/blob/main/README.md

Basic async usage: log in, resolve a username to a user ID, and fetch up to 20 user media items.

```python
from aiograpi import Client

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

user_id = await cl.user_id_from_username(ACCOUNT_USERNAME)
medias = await cl.user_medias(user_id, 20)
```
Tokens:
Raw