igapi-rs 0.0.5.dev0

Python bindings for Instagram Private API

igapi-rs

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

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

• 文档: igapi-rs.es007.com
• 源码: github.com/open-luban/igapi-rs

安装

pip install igapi-rs

环境要求

• Python 3.10+

快速开始

import igapi

# 创建客户端
client = igapi.Client()

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

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

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

# 获取用户动态
feed = client.user_feed(12345678)
for media in feed.items:
    print(f"媒体: {media.id}, 点赞: {media.like_count}")

API 参考

Client

Client(proxy: str | None = None, platform: str = "android")

创建新的 Instagram API 客户端。

参数:

• proxy (可选): 代理 URL（例如 "http://localhost:8080"）
• platform (可选): 使用的平台（"android" 或 "web"）

方法:

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

登录 Instagram。

异常:

• PermissionError: 登录失败（密码错误、需要验证等）
• ValueError: 无效的凭据
• RuntimeError: 网络或 API 错误

is_logged_in() -> bool

检查当前是否已登录。

user_info(user_id: int) -> User

通过 ID 获取用户信息。

异常:

• KeyError: 用户未找到
• PermissionError: 需要登录

search_users(query: str) -> list[User]

通过用户名或名称搜索用户。

user_feed(user_id: int, max_id: str | None = None) -> Feed

获取用户的媒体动态。

参数:

• user_id: 要获取动态的用户 ID
• max_id (可选): 分页游标

类型定义

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

class Feed:
    items: list[Media]      # 媒体项目列表
    has_more: bool          # 是否有更多项目
    next_cursor: str | None # 下一页游标

错误处理

try:
    client.login("user", "pass")
except PermissionError as e:
    # 登录失败、需要验证、双因素认证等
    print(f"登录错误: {e}")
except ValueError as e:
    # 无效的凭据
    print(f"无效输入: {e}")
except RuntimeError as e:
    # API 或网络错误
    print(f"错误: {e}")

使用代理

# HTTP 代理
client = igapi.Client(proxy="http://localhost:8080")

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

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

示例

完整使用示例请参见 examples/python_example.py。

开发

构建

# 调试构建
maturin develop

# 发布构建
maturin develop --release

# 构建 wheel 包
maturin build --release

测试

# 运行测试
python -m pytest tests/

# 类型检查
mypy --strict examples/

性能

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

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

许可证

MIT OR Apache-2.0

链接

• 在线文档
• GitHub 仓库
• PyPI