igapi-rs 0.1.5.dev0

Python bindings for Instagram Private API

igapi-rs

Instagram 私有 API 的 Python 绑定，基于 Rust + PyO3 构建，高性能、异步优先。

支持 Android / iOS / Web 三平台模拟。

• 文档: igapi-rs.es007.com
• LLM 速查: 索引 / Python API
• 源码: github.com/open-luban/igapi-rs

安装

pip install igapi-rs

环境要求

• Python 3.10+

快速开始

import asyncio
import igapi
from igapi.android import Client

async def main():
    # 创建客户端
    client = Client()

    # 登录
    await client.login("username", "password")

    # 获取用户信息
    user_api = igapi.UserApi(client)
    user = await user_api.info(12345678)
    print(f"用户: @{user.username}")
    print(f"粉丝数: {user.follower_count}")

    # 搜索用户
    results = await user_api.search("instagram")
    for user in results:
        print(f"@{user.username}")

    # 获取用户动态
    feed_api = igapi.FeedApi(client)
    items, next_cursor = await feed_api.user(12345678)
    for media in items:
        print(f"媒体: {media.id}, 点赞: {media.like_count}")

asyncio.run(main())

API 参考

Android Client

from igapi.android import AccountInfo, Client

Client(
    proxy: str | None = None,
    danger_accept_invalid_certs: bool = False,
    http1_only: bool = False,
    account: AccountInfo | None = None,
)

创建 Android 平台客户端。

参数:

• proxy (可选): 代理 URL（例如 "http://localhost:8080"）
• danger_accept_invalid_certs (可选): 是否接受无效 TLS 证书
• http1_only (可选): 是否强制 HTTP/1.1
• account (可选): igapi.android.AccountInfo

方法:

await login(username: str, password: str) -> None

登录 Instagram。

异常:

• ValueError: 密码错误、用户无效
• PermissionError: 需要重新登录 / 账号锁定 / 需要同意条款
• igapi.TwoFactorRequired / igapi.ChallengeRequired: 需要 2FA / 安全验证
• RuntimeError: 网络或 API 错误

await is_logged_in() -> bool

检查当前是否已登录。

会话与登出（全平台）

• await logout() -> None：调用登出端点并清除内存登录态（登出后仍可重新 login()）
• await save_session(path: str) -> None：用 FileSessionStorage 将当前会话写入本地 JSON 文件
• await restore_session(path: str) -> None：从 save_session() 写入的 JSON 文件恢复会话
• export_account() -> AccountInfo：导出完整账号状态（Android/Web，同步，不需 await；iOS 暂不支持）
• export_account_string() -> str：导出平台账号字符串（Android/Web，同步；iOS 暂不支持）

save_session/restore_session 的 JSON 格式与 export_account_string() 的账号字符串格式不同，两者不可混用读写。

资源 API 一览

所有资源 API 均以 igapi.XxxApi(client) 构造，方法为 async。完整签名见 Python LLM 速查 或 LLM 索引：

资源 API	主要方法	可用平台
igapi.UserApi	info / search / id_from_username / info_by_username / web_id_from_username	全平台；web_id_from_username 仅 Web
igapi.MediaApi	info / info_by_shortcode	全平台
igapi.FeedApi	user / user_all	全平台
igapi.UploadApi	photo / configure / photo_web / configure_web(web)	全平台
igapi.PostApi	user_posts / create_photo	仅 igapi.web.Client
igapi.DirectApi	create_group_thread(web) / create_group_thread_graphql(web) / send_text(web) / send_text_to_thread(web) / send_text_broadcast(android+web)	Android / Web

平台命名空间

平台必须通过显式命名空间选择，不再从 igapi 顶层导入全局客户端或全局 AccountInfo：

from igapi.android import AccountInfo as AndroidAccountInfo
from igapi.android import Client as AndroidClient
from igapi.ios import Client as IosClient
from igapi.web import AccountInfo as WebAccountInfo
from igapi.web import Client as WebClient

android = AndroidClient()
ios = IosClient()
web = WebClient()

Android 从结构化账号信息恢复 session：

from igapi.android import AccountIdentity, AccountInfo, Client, DeviceInfo, SessionInfo

account = AccountInfo(
    identity=AccountIdentity("username", "password"),
    device=DeviceInfo("android_id", "phone_id", "uuid", "device_id"),
    session=SessionInfo(sessionid="...", ds_user_id=123456789),
)
client = Client(account=account)

Android 和 Web 均支持账号字符串入口恢复 session：

from igapi.android import AccountInfo as AndroidAccountInfo
from igapi.web import AccountInfo, Client

android_account = AndroidAccountInfo.parse(
    "username:password||android_id;phone_id;uuid;device_id|sessionid=...; ds_user_id=...||"
)
account = AccountInfo.parse("username:password||csrf_token|sessionid=...; ds_user_id=...||")
client = Client(account=account)

account_str = client.export_account_string()

类型定义

User

class User:
    pk: int                 # 用户 ID
    username: str           # 用户名
    full_name: str          # 全名
    is_private: bool        # 是否私密账户
    profile_pic_url: str    # 头像 URL
    follower_count: int     # 粉丝数
    following_count: int    # 关注数

Media

class Media:
    id: str                 # 媒体 ID
    media_type: int         # 类型（1=图片, 2=视频, 8=轮播）
    caption_text: str       # 描述文字
    like_count: int         # 点赞数
    comment_count: int      # 评论数

Feed API 不返回独立的 Feed 类型，而是直接返回二元组：

items, next_cursor = await igapi.FeedApi(client).user(12345678)

错误处理

import asyncio
import igapi
from igapi.android import Client

async def main():
    client = Client()

    try:
        await client.login("user", "pass")
    except igapi.TwoFactorRequired as e:
        print(f"需要双因素认证: {e}")
    except igapi.ChallengeRequired as e:
        print(f"需要安全验证: {e}")
    except PermissionError as e:
        print(f"登录错误: {e}")
    except ValueError as e:
        print(f"无效输入: {e}")
    except RuntimeError as e:
        print(f"错误: {e}")

asyncio.run(main())

使用代理

# HTTP 代理
from igapi.android import Client

client = Client(proxy="http://localhost:8080")

# HTTPS 代理
client = Client(proxy="https://proxy.example.com:8080")

# SOCKS 代理
client = Client(proxy="socks5://localhost:1080")

示例

更多完整示例请参见仓库根目录的 docs/getting-started/快速上手.md 和 docs/api/。

开发

构建

# 调试构建
maturin develop --manifest-path src/py/Cargo.toml

# 发布构建
maturin develop --release --manifest-path src/py/Cargo.toml

# 构建 wheel 包
maturin build --release --manifest-path src/py/Cargo.toml

测试

# 运行测试
python -m pytest tests/

# 类型检查
mypy --strict examples/

性能

Python 绑定使用 PyO3，保持接近原生 Rust 的性能：

• API 调用通过 Tokio 异步处理
• 最小化序列化开销
• 尽可能使用零拷贝数据访问

许可证

MIT OR Apache-2.0

链接

• 在线文档
• GitHub 仓库
• PyPI