igapi 数据类型参考¶

1. 概述¶

igapi 模块提供以下数据类型，用于描述从 Instagram API 返回或传入的结构化数据：

类型	用途
`User`	Instagram 用户信息，包含 ID、用户名、是否私密等
`Media`	帖子/媒体信息，包含类型、标题、点赞数等
`igapi.android.AccountInfo` / `igapi.web.AccountInfo`	平台账号凭证与 Session 信息，支持序列化与恢复
`igapi.ios.AccountInfo`	iOS 账号信息占位类型；当前不支持 `parse()` 字符串恢复，也不支持通过 `Client(account=...)` 恢复
`UploadProgress`	上传进度保留类型；当前 Python 公共 API 暂不返回，Rust core 进度回调使用
`UploadResult`	上传完成后服务端返回的结果

所有类型均为只读属性（不可直接赋值）。Android/Web 账号信息通过对应平台命名空间下的 AccountInfo.parse() 构造。

2. User¶

User 表示一个 Instagram 用户的公开信息。

通过 igapi.UserApi(client).info(user_id) 或搜索接口返回。

属性¶

属性名	类型	说明
`pk`	`int`	用户数字 ID（永久唯一标识符）
`username`	`str`	用户名（不含 `@`）
`full_name`	`str`	账号昵称/全名
`is_private`	`bool`	是否为私密账号
`profile_pic_url`	`str`	头像图片 URL
`follower_count`	`int`	粉丝数（见注意事项）
`following_count`	`int`	关注数（见注意事项）

示例¶

import asyncio
import igapi

async def main():
    client = igapi.android.Client()
    await client.login("your_user", "your_pass")

    # 通过用户 ID 查询
    user_api = igapi.UserApi(client)
    user = await user_api.info(123456789)

    print(user.pk)               # 123456789
    print(user.username)         # "john_doe"
    print(user.full_name)        # "John Doe"
    print(user.is_private)       # False
    print(user.profile_pic_url)  # "https://..."
    print(user.follower_count)   # 1024
    print(user.following_count)  # 512

    print(repr(user))
    # User(pk=123456789, username='john_doe', full_name='John Doe', followers=1024, following=512)

asyncio.run(main())

注意事项¶

follower_count 和 following_count 在搜索接口（search_users）返回的结果中固定为 0，仅在通过 igapi.UserApi(client).info(pk) 精确查询时才有正确数值。需要粉丝数时，请先获取 pk 再单独调用 info()。

3. Media¶

Media 表示一条 Instagram 帖子（图片、视频或轮播）。

通过 igapi.MediaApi(client).info(media_id) 或 Feed 接口返回。

属性¶

属性名	类型	说明
`id`	`str`	媒体 ID（字符串格式）
`media_type`	`int`	媒体类型（见下表）
`caption_text`	`str`	帖子标题文本，无标题时为空字符串
`like_count`	`int`	点赞数
`comment_count`	`int`	评论数，无法获取时为 `0`

media_type 值说明¶

值	含义
`1`	Photo（单张图片）
`2`	Video（视频）
`8`	Carousel（多图/轮播）

示例¶

import asyncio
import igapi

async def main():
    client = igapi.android.Client()
    await client.login("your_user", "your_pass")

    media_api = igapi.MediaApi(client)
    media = await media_api.info("3456789012345678901_123456")

    print(media.id)            # "3456789012345678901_123456"
    print(media.media_type)    # 1
    print(media.caption_text)  # "今天天气不错 #sunnyDay"
    print(media.like_count)    # 2048
    print(media.comment_count) # 37

    # 判断媒体类型
    if media.media_type == 1:
        print("这是图片")
    elif media.media_type == 2:
        print("这是视频")
    elif media.media_type == 8:
        print("这是轮播")

    print(repr(media))
    # Media(id='3456789012345678901_123456', type=1, likes=2048, comments=37)

asyncio.run(main())

4. AccountInfo¶

AccountInfo 用于序列化和恢复账号的完整状态，包括用户名、密码、设备标识和 Session Cookie。Android/Web 平台适用于持久化存储账号以避免重复登录；iOS 平台的账号字符串解析和 Client(account=...) 恢复当前暂未实现。

账号字符串格式¶

AccountInfo 使用以下紧凑字符串格式存储：

Android 平台：

用户名:密码||android_id;phone_id;uuid;device_id|cookies||

Web 平台：

用户名:密码||csrf_token|cookies||

其中 cookies 段包含 sessionid、ds_user_id、mid 等 Cookie 键值对。

类方法¶

`AccountInfo.parse(s)`¶

从当前平台的账号字符串解析 AccountInfo 对象。

参数	类型	默认值	说明
`s`	`str`	—	账号字符串

返回 AccountInfo。解析失败时抛出 ValueError。

实例方法¶

`to_account_string()`¶

将当前账号信息序列化为字符串，可用于存储或传输。返回与 parse() 兼容的格式字符串。

属性¶

通用属性（Android 与 Web 均有）：

属性名	类型	说明
`username`	`str`	用户名
`password`	`str`	密码（明文存储，注意安全）
`platform`	`str`	平台名称，如 `android` / `web`；iOS 类型暂不支持从字符串恢复
`has_session`	`bool`	是否含有有效的 Session Cookie
`user_id`	`int \\| None`	用户数字 ID，无 Session 时为 `None`
`session_id`	`str \\| None`	Session ID 原始字符串，无 Session 时为 `None`
`mid`	`str \\| None`	Machine ID，来自 Cookie
`ds_user_id`	`int \\| None`	Cookie 中的用户 ID 字段

Android 专属属性（Web 平台下均为 None）：

属性名	类型	说明
`android_id`	`str \\| None`	Android 设备 ID，如 `android-60a691d2387706c4`
`phone_id`	`str \\| None`	Phone UUID
`uuid`	`str \\| None`	设备 UUID
`device_id`	`str \\| None`	Device UUID（通常与 `uuid` 相同）
`advertising_id`	`str \\| None`	Android 广告 ID，部分移动端请求会作为设备画像字段使用

Web 专属属性（Android 平台下为 None）：

属性名	类型	说明
`csrf_token`	`str \\| None`	CSRF Token，用于 Web 请求签名

示例¶

import asyncio
import igapi
from igapi.android import Client as AndroidClient, AccountInfo as AndroidAccountInfo
from igapi.web import Client as WebClient, AccountInfo as WebAccountInfo

async def main():
    # --- Android 账号 ---

    # 1. 首次登录后导出
    client = AndroidClient()
    await client.login("john_doe", "mypassword")
    account = client.export_account()
    account_str = account.to_account_string()
    # 将 account_str 保存到数据库或文件

    # 2. 下次从字符串恢复
    account = AndroidAccountInfo.parse(account_str)
    print(account.username)     # "john_doe"
    print(account.platform)     # "android"
    print(account.has_session)  # True
    print(account.user_id)      # 123456789

    # 访问 Android 设备信息
    print(account.android_id)   # "android-60a691d2387706c4"
    print(account.phone_id)     # "7dd70327-354a-4a61-8bb8-79fb3963ebb1"

    # 用账号信息重建客户端（跳过登录）
    client = AndroidClient(account=account)

    # --- Web 账号 ---

    web_account = WebAccountInfo.parse(
        "<username>:<password>||<csrf_token>|sessionid=<sessionid>; ds_user_id=<user_id>||"
    )
    print(web_account.csrf_token)  # "csrf_token_value"
    web_client = WebClient(account=web_account)

    print(repr(account))
    # AccountInfo(username='john_doe', platform='android', has_session=True, user_id=123456789)

asyncio.run(main())

password 以明文形式存储在账号字符串中。请勿将账号字符串存储在不安全的位置（如日志文件、版本控制系统）。

5. 平台命名空间¶

Python 用户层不暴露全局 PlatformType / AccountInfo。平台由命名空间表达：

平台	客户端	账号信息
Android	`igapi.android.Client`	`igapi.android.AccountInfo`
iOS	`igapi.ios.Client`	`igapi.ios.AccountInfo`（暂不支持 `parse()` 恢复）
Web	`igapi.web.Client`	`igapi.web.AccountInfo`

不同平台的账号字符串结构不同，必须使用对应平台的 AccountInfo.parse()。当前仅 Android 和 Web 平台支持账号字符串解析与恢复。

6. UploadProgress¶

UploadProgress 描述图片或视频上传过程中的进度快照。当前 Python 公共上传 API 暂未绑定 photo_with_progress / configure_with_progress，因此不会主动返回或回调该类型；它主要对应 Rust core 的进度回调能力，并作为后续 Python 进度回调绑定的保留类型。

属性¶

属性名	类型	说明
`uploaded_bytes`	`int`	已上传字节数
`total_bytes`	`int`	总字节数
`stage`	`str`	当前阶段（见下表）
`percentage`	`float`	上传完成比例，范围 `0.0` 至 `1.0`（`0.5` 表示 50%，显示百分比需乘以 100）

stage 值说明¶

stage 为中文阶段描述字符串，取值如下：

值	含义
`"准备中"`	初始化上传会话
`"上传中"`	传输文件数据
`"配置中"`	服务端处理媒体
`"已完成"`	上传完成

实例方法¶

`is_complete()`¶

返回 bool，当 stage 为 "已完成" 时为 True。

示例¶

import asyncio
import igapi

def handle_progress(progress: igapi.UploadProgress):
    print(f"阶段: {progress.stage}")
    print(f"进度: {progress.percentage * 100:.1f}%")
    print(f"已传: {progress.uploaded_bytes} / {progress.total_bytes} 字节")

    if progress.is_complete():
        print("上传完成！")

async def main():
    client = igapi.android.Client()
    await client.login("your_user", "your_pass")

    with open("/path/to/photo.jpg", "rb") as f:
        image_data = f.read()

    # 当前 Python 上传 API 不接受 progress 回调；该类型用于描述 Rust core 进度回调数据结构。
    result = await igapi.UploadApi(client).photo(image_data)
    print(f"上传完成，upload_id={result.upload_id}")

    # UploadProgress 实例的 repr 形如：
    # UploadProgress(stage='上传中', progress=50.0%)

asyncio.run(main())

7. UploadResult¶

UploadResult 是上传完成后服务端返回的结果，包含上传 ID 与状态。

通过 igapi.UploadApi(client).photo() 等上传方法返回。

属性¶

属性名	类型	说明
`upload_id`	`str`	服务端分配的上传唯一标识符
`status`	`str`	上传状态，通常为 `"ok"`
`offset`	`int`	已确认接收的字节偏移量，断点续传时使用

示例¶

import asyncio
import igapi

async def main():
    client = igapi.android.Client()
    await client.login("your_user", "your_pass")

    with open("/path/to/photo.jpg", "rb") as f:
        image_data = f.read()

    result = await igapi.UploadApi(client).photo(image_data)

    print(result.upload_id)  # "174567890123456789"
    print(result.status)     # "ok"
    print(result.offset)     # 204800

    print(repr(result))
    # UploadResult(upload_id='174567890123456789', status='ok', offset=204800)

asyncio.run(main())

upload_id 在调用发布（configure）接口时需要用到，通常由 igapi.UploadApi(client).photo() 内部自动处理，无需手动传递。

8. 类型汇总表¶

类型	构造方式	主要用途
`User`	由 API 方法返回	读取用户公开信息
`Media`	由 API 方法返回	读取帖子内容与统计
平台 `AccountInfo`	`igapi.android.AccountInfo.parse(s)` / `igapi.web.AccountInfo.parse(s)` 或 `client.export_account()`	持久化与恢复登录状态
`UploadProgress`	保留类型 / Rust core 进度回调数据结构	Python 当前公共 API 暂不返回
`UploadResult`	由上传方法返回	获取上传结果标识符

所有类型均支持 repr()，可直接用于调试输出。

igapi 数据类型参考¶

1. 概述¶

2. User¶

属性¶

示例¶

注意事项¶

3. Media¶

属性¶

media_type 值说明¶

示例¶

4. AccountInfo¶

账号字符串格式¶

类方法¶

AccountInfo.parse(s)¶

实例方法¶

to_account_string()¶

属性¶

示例¶

5. 平台命名空间¶

6. UploadProgress¶

属性¶

stage 值说明¶

实例方法¶

is_complete()¶

示例¶

7. UploadResult¶

属性¶

示例¶

8. 类型汇总表¶

相关文档¶

`AccountInfo.parse(s)`¶

`to_account_string()`¶

`is_complete()`¶